139 lines
5.4 KiB
Markdown
139 lines
5.4 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
TAURI_ENV_TARGET_TRIPLE=x86_64-pc-windows-msvc yarn server:build
|
|
```
|