VizTyp/server/README.md

VizTyp Backend Server / VizTyp 后端服务

VizTyp 知识管理的 HTTP 后端服务。Web 端和 Tauri 桌面端共用同一套 HTTP API。 HTTP backend for VizTyp knowledge management. Shared by web and Tauri desktop via one HTTP API.

架构 / Architecture

• Runtime: tokio
• HTTP: hyper 1.x + hyper-util(官方配套)
• 序列化: serde + serde_json
• 认证: jsonwebtoken(JWT)+ sha2(SHA-256 密码哈希)
• 存储: JSON 文件(元数据)+ .typ 文件(内容),无数据库

API / 接口

认证 / Auth

Method	Path	功能 / Function	认证
POST	/api/auth/register	注册(首用户自动 owner)	公开
POST	/api/auth/login	登录(返回 JWT)	公开
GET	/api/auth/me	当前用户信息	JWT
GET	/api/auth/status	是否有注册用户	公开
GET	/api/users	列出所有用户	JWT

知识库与文档 / KB & Docs

Method	Path	功能 / Function	认证
GET	/api/workspace	获取工作空间(含所有 KB 元数据)	—
POST	/api/kb	创建知识库	—
GET	/api/kb/:id/docs	列出 KB 下所有文档(递归)	KB 读权限
GET	/api/kb/:id/tags	列出 KB 标签	KB 读权限
GET/POST/DELETE	/api/kb/:id/collaborators	协作者 CRUD	KB 写权限
POST	/api/kb/:id/access-code	设置 KB 访问码	KB 写权限
GET	/api/doc/:id	读取文档(含 draft_content/status/tags)	KB 读权限
PUT	/api/doc/:id	保存文档({content, draft})	KB 写权限
POST	/api/doc	创建文档	KB 写权限
POST	/api/doc/:id/publish	发布草稿(提升为发布版)	KB 写权限

版本历史 / Version History

Method	Path	功能 / Function
GET	/api/doc/:id/versions	列出版本快照
POST	/api/doc/:id/versions	保存版本快照
POST	/api/doc/:id/versions/:vid/restore	恢复到指定版本

标签 / Tags

Method	Path	功能 / Function
GET	/api/doc/:id/tags	读取文档标签
PUT	/api/doc/:id/tags	设置文档标签

搜索与分享 / Search & Share

Method	Path	功能 / Function
POST	/api/search	权限感知全文搜索(body: {q, kb_ids})
POST	/api/share	创建分享令牌
GET/POST	/api/share/:token	通过令牌访问(GET 公开,POST 可带访问码)
DELETE	/api/share/:token	删除分享
GET	/api/doc/:id/share	查询文档的分享令牌

工作区与状态 / Workspace & Presence

Method	Path	功能 / Function	认证
GET	/api/workspace/export	导出整个工作区(含文档内容)	JWT
POST	/api/workspace/import	导入工作区(body: {data, overwrite})	JWT
GET	/api/presence	在线状态(记录心跳 + 列出在线用户)	JWT

所有响应统一格式:{"ok": true, "data": ...} 或 {"ok": false, "error": "..."}。

权限层级 / Permission tiers:

• public:任何人可读
• private / specified:需 JWT 身份且有协作者角色(owner 对所有 KB 有 admin)
• access_code:需有效访问码(X-Access-Code header)或有角色
• 写权限:reader 禁止写,writer/admin 允许

运行 / Run

cd server
cargo run

# 自定义端口/数据目录 / Custom port / data dir
VIZTYP_PORT=8000 VIZTYP_DATA_DIR=/path/to/data cargo run

# JWT secret (缺省用临时值, 生产环境务必设置) / JWT secret
VIZTYP_JWT_SECRET=your-secret cargo run

默认地址 http://127.0.0.1:7480,数据目录 ~/.viztyp/data/。

存储布局 / Storage layout

~/.viztyp/data/
├── workspace.json         # Workspace + KB[] 元数据
├── users.json             # 用户表 (id → User, 含密码哈希)
├── kb_collaborators.json  # KB 协作者 (kb_id → [(user_id, role)])
├── versions.json          # 版本快照 (doc_id → [DocVersion])
├── doc_tags.json          # 文档标签 (doc_id → [tag])
├── shares.json            # 分享令牌 (token → DocShare)
├── access_codes.json      # KB 访问码 (kb_id → code)
├── presence.json          # 在线状态 (user_id → Presence)
├── kbs/                   # KB 快照目录
└── <root_path>/           # KB 实际文件目录 (创建时指定)
    ├── *.typ              # 发布版文档
    └── *.typ.draft        # 草稿 sidecar (发布后清除)

与前端集成 / Frontend integration

• Web 端:前端 VIZTYP_API_URL 环境变量指向本服务(默认 http://127.0.0.1:7480)
• Tauri 桌面端:作为 sidecar 自动启动
  • yarn dev(debug):src-tauri/src/lib.rs 用 std::process::Command spawn(需先在 server/ 运行 cargo build)
  • yarn build(release):先 yarn server:build 生成 src-tauri/binaries/viztyp-server-<triple>,再用 tauri-plugin-shell 的 app.shell().sidecar()(打包进安装包)
  • 应用退出时通过 RunEvent::Exit 自动 kill 子进程

打包流程 / Bundling

# 1. 构建 sidecar (带 target-triple 后缀) / Build sidecar with triple suffix
yarn server:build

# 2. 完整桌面打包 (含 sidecar) / Full desktop bundle
yarn build

scripts/build-sidecar.sh 自动读取 TAURI_ENV_TARGET_TRIPLE(Tauri 注入)或宿主 triple。

交叉编译示例 / Cross-compile:

TAURI_ENV_TARGET_TRIPLE=x86_64-pc-windows-msvc yarn server:build