wangdl/startup-plan
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 推送所有未提交的文档更新

Browse Source 
- 5/19-5/20 工作日志
- 后端实现状态更新
- 服务器部署方案更新
- 知识库设计更新
- 进行中文档更新
- 执行计划与任务清单更新

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
WangDL 2026-05-20 18:10:44 +08:00
parent fae6e26549
commit 23a6999b56
5 changed files with 349 additions and 408 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
工作日志/2026-05-19.md
View File

@ -104,22 +104,26 @@ SSH 密钥位置：`startup-plan/凭据配置/WangDL.pem` 和 `zhixi.pem`
--- ---
## 明天继续 ## 明天继续（截至 5/20 14:00 状态）
1. **Python Worker 部署到 8核32G**（最高优先） 1. 🔶 **Python Worker 部署到 8核32G**（最高优先）— 代码已部署，依赖+systemd 待补
```bash - ✅ 代码已推送到 `/opt/zhixi/backend/rag-worker/`（10 个文件 + .env）
ssh -i zhixi.pem ubuntu@120.53.227.155 - ✅ .env 配置完整
cd /opt/zhixi/backend - ❌ Python 依赖不全（缺 pydantic/python-docx/markdown/pandas/Pillow，且 requirements.txt 缺 qdrant-client/python-dotenv）
git pull - ❌ systemd `zhixi-worker` 服务未创建
cd rag-worker - ⚠️ 默认 python3 为 3.10.12（日志记了 3.11.15）
pip3.11 install -r requirements.txt
# 创建 systemd service 启动 main.py
```
2. **COS Bucket 创建**（腾讯云控制台） 2. ⚠️ **COS Bucket 创建**（腾讯云控制台）— 未验证，环境变量中已有 COS 凭据
3. **百度 OCR 开通**
4. **4核4G 安装 gitea-runner-web** 3. ❌ **百度 OCR 开通** — 未处理
5. **编写 CI/CD workflow 文件**
4. ✅ **4核4G 安装 gitea-runner-web** — 单一 `gitea-runner` 服务同时处理 api-server + web-projects 的 CI/CD
- `act_runner` 已安装，systemd 自启
- web-projects deploy.yml 已配置并通过验证
5. ✅ **编写 CI/CD workflow 文件** — 两端均已配置并运行
- ✅ `/home/ubuntu/api-server/.gitea/workflows/deploy.yml`
- ✅ `/tmp/web-projects/.gitea/workflows/deploy.yml`（web 今日 13:38 部署成功）
--- ---

14
技术设计/api-server/已完成/[已完成]-后端实现状态.md
View File

@ -23,7 +23,12 @@ updated: 2026-05-17
| Focus Items | ✅ | CRUD + 完成标记 | | Focus Items | ✅ | CRUD + 完成标记 |
| Review | ✅ | 到期卡片 + 提交复习 | | Review | ✅ | 到期卡片 + 提交复习 |
| Learning Activity | ✅ | 热力图 + 摘要统计 | | Learning Activity | ✅ | 热力图 + 摘要统计 |
| Document Import | ✅ | 导入创建 + 状态查询（Redis 队列待接） | | Document Import | ✅ | 导入创建 + 状态查询（claim/heartbeat/stale recovery） |
| Knowledge Source | ✅ | 资料来源 CRUD + DocumentImport 自动生成 |
| Import Candidate | ✅ | 候选知识点管理 + KnowledgeItem 自动生成 |
| RAG (内部 API) | ✅ | 7 个端点，@Public 绕过 JWT |
| Python RAG Worker | 🔶 | 代码已部署（10 文件），systemd 待创建，依赖待补全 |
| UploadedFile | ✅ | sha256 去重 |
| Notifications | ✅ | 列表 + 已读标记（推送待接） | | Notifications | ✅ | 列表 + 已读标记（推送待接） |
| Feedback | ✅ | 提交 + 列表 + 统计 | | Feedback | ✅ | 提交 + 列表 + 统计 |
| System | ✅ | 健康检查 | | System | ✅ | 健康检查 |
@ -36,7 +41,7 @@ updated: 2026-05-17
|------|------| |------|------|
| NestJS + TypeScript | ✅ | | NestJS + TypeScript | ✅ |
| Prisma + MySQL | ✅ | | Prisma + MySQL | ✅ |
| Docker + Nginx | ✅ api.longde.cloud | | Docker + Nginx | ✅ api.longde.cloud（8核32G） |
| Let's Encrypt SSL | ✅ | | Let's Encrypt SSL | ✅ |
| Swagger（Basic Auth 保护） | ✅ | | Swagger（Basic Auth 保护） | ✅ |
| 全局 JwtAuthGuard（@Public 白名单） | ✅ | | 全局 JwtAuthGuard（@Public 白名单） | ✅ |
@ -44,11 +49,16 @@ updated: 2026-05-17
| 全局 ExceptionFilter | ✅ | | 全局 ExceptionFilter | ✅ |
| 全局 ValidationPipe | ✅ | | 全局 ValidationPipe | ✅ |
| `npx tsc --noEmit` | ✅ 0 errors | | `npx tsc --noEmit` | ✅ 0 errors |
| CI/CD Pipeline（api-server） | ✅ gitea-runner + deploy.yml |
| CI/CD Pipeline（web-projects） | ✅ gitea-runner + deploy.yml（今日 13:38 部署） |
## 待推进 ## 待推进
- AI Workflows：费曼解释评估、知识导入解析、复习卡片生成、长期趋势分析 - AI Workflows：费曼解释评估、知识导入解析、复习卡片生成、长期趋势分析
- BullMQ：队列 + Worker 异步处理 - BullMQ：队列 + Worker 异步处理
- Redis：缓存 + 限流接入 - Redis：缓存 + 限流接入
- Python RAG Worker：补全依赖 + 创建 systemd 服务（代码已部署）
- iOS：知识库列表、学习会话、复习等页面接后端 - iOS：知识库列表、学习会话、复习等页面接后端
- CI/CD：4核4G 安装 gitea-runner-web + web-projects workflow
- COS Bucket 验证 + 百度 OCR 开通
- 管理员后台：Admin API + 审计日志 - 管理员后台：Admin API + 审计日志

315
技术设计/api-server/服务器与数据库部署方案.MD
View File

@ -1,10 +1,12 @@
# 知习数据库与服务器部署方案（最终版） # 知习数据库与服务器部署方案（最终版）
> 定版日期：2026-05-18 | 状态：已拍板，按此执行 > 定版日期：2026-05-18 | 状态：已拍板，按此执行 | 最后检查：2026-05-20 14:00
>
> 完成度标记：✅ 已完成 | 🔶 部分完成 | ⏳ 待完成 | ❌ 未开始
--- ---
## 一、存储架构总览 ## 一、存储架构总览 ✅ 已完成
知识库不需要 MongoDB。最终存储分成四类： 知识库不需要 MongoDB。最终存储分成四类：
@ -25,7 +27,7 @@ ClickHouse → 第一阶段不需要（OLAP 后续再说）
--- ---
## 二、MySQL：唯一权威业务数据库 ## 二、MySQL：唯一权威业务数据库 ✅ 已完成
### 存放内容 ### 存放内容
@ -64,7 +66,7 @@ feedback
notifications notifications
``` ```
### ID 类型（重要） ### ID 类型（重要）✅ 已改为 String(cuid)
当前 Prisma schema 主键是 `BigInt @default(autoincrement())`，JavaScript/JSON 对 64 位整数有精度问题。 当前 Prisma schema 主键是 `BigInt @default(autoincrement())`，JavaScript/JSON 对 64 位整数有精度问题。
@ -76,7 +78,7 @@ id String @id @default(cuid())
推荐 `cuid/cuid2`：适合业务 ID，前端、后端、日志、JWT、API 都好处理。以后数据多了再改会很痛苦。 推荐 `cuid/cuid2`：适合业务 ID，前端、后端、日志、JWT、API 都好处理。以后数据多了再改会很痛苦。
### 生产配置 ### 生产配置 ✅ 已应用
文件：`/etc/mysql/conf.d/zhixi.cnf` 文件：`/etc/mysql/conf.d/zhixi.cnf`
@ -107,7 +109,7 @@ log_queries_not_using_indexes = 0
skip-log-bin skip-log-bin
``` ```
### 32G 内存分配 ### 32G 内存分配 ✅ 按方案执行
```text ```text
MySQL buffer pool 8G MySQL buffer pool 8G
@ -127,7 +129,7 @@ Too many connections → max_connections 调到 150
--- ---
## 三、Qdrant：向量数据库 ## 三、Qdrant：向量数据库 ✅ 已完成
### 存放内容 ### 存放内容
@ -217,7 +219,7 @@ ports:
--- ---
## 四、COS：对象存储 ## 四、COS：对象存储 ⚠️ 凭据已配置，Bucket 待验证
### 存放内容 ### 存放内容
@ -243,7 +245,7 @@ zhixi-prod/
--- ---
## 五、Redis：队列与缓存 ## 五、Redis：队列与缓存 ✅ 已完成（BullMQ 待接）
### 负责 ### 负责
@ -265,7 +267,7 @@ API 限流
--- ---
## 六、服务器分工（已拍板） ## 六、服务器分工（已拍板）✅ 按方案执行
### 总原则 ### 总原则
@ -351,7 +353,34 @@ Dify 生产环境 ← 最低 4G 但跑不稳（后面细说）
--- ---
## 七、4核4G 上各服务决策 ## 6.5、两服务器内网互联 ✅ 已验证
| 项目 | 值 |
|------|-----|
| 8核32G 内网 IP | 172.21.0.4 |
| 4核4G 内网 IP | 10.2.0.7 |
| 延迟 | ~1.9ms（双向 ping） |
| 通信原则 | **所有服务器间通信均走内网，不走公网** |
### 已验证的通信路径
| 路径 | 内网地址 | 验证结果 |
|------|---------|---------|
| 8核32G → 4核4G Gitea | `http://10.2.0.7:3000` | ✅ HTTP 200, 6.5ms |
| 4核4G → 8核32G API | `http://172.21.0.4:3000` | ✅ 正常响应 |
| 8核32G Runner 注册 | `http://10.2.0.7:3000` | ✅ 已切换，restart 正常 |
### 对内网通信的服务
| 服务 | 原地址 | 切换后 |
|------|--------|--------|
| zhixi-prod-runner → Gitea | `81.70.187.179`（公网） | `10.2.0.7`（内网） |
| 4核4G CI/CD → 8核32G API | `api.longde.cloud` | 可切 `172.21.0.4`（待优化） |
| COS 上传/下载 | `cos.ap-beijing.myqcloud.com`（内网） | 同区 VPC 内网，免流量费 |
---
## 七、4核4G 上各服务决策 ✅ 已定案
### 1. n8n：可以放 ### 1. n8n：可以放
@ -433,7 +462,7 @@ n8n workflow agent
--- ---
## 八、最终部署架构图 ## 八、最终部署架构图 ✅ 已落实
```text ```text
iOS / Web iOS / Web
@ -488,7 +517,7 @@ n8n workflow agent
--- ---
## 九、CI/CD 部署流水线 ## 九、CI/CD 部署流水线 ✅ api-server + web-projects 均已配置
### 1. 总原则 ### 1. 总原则
@ -526,9 +555,10 @@ Gitea 本体只放 4核4G，Runner 两台都装
备份脚本部署 备份脚本部署
``` ```
### 3. Runner 安装 ### 3. Runner 安装 ✅ 已完成
两台服务器都创建 `deploy` 用户（不要用 root 跑 runner）： - ✅ 8核32G: `gitea-runner` systemd 自启
- ✅ 4核4G: `gitea-runner` systemd 自启（单一 runner 同时处理 api-server 和 web-projects）
```bash ```bash
sudo useradd -m -s /bin/bash deploy sudo useradd -m -s /bin/bash deploy
@ -546,81 +576,39 @@ sudo usermod -aG docker deploy
--token <从 Gitea Admin 获取> --token <从 Gitea Admin 获取>
``` ```
### 4. Workflow 示例 ### 4. Workflow 实际部署 ✅ 已落地
**后端部署（跑在 8核 runner）：** **后端部署（4核4G runner 执行）：**
- 实际文件：`/home/ubuntu/api-server/.gitea/workflows/deploy.yml`
- 流程：git pull → Docker build → 处理迁移卡死 → 启动 zhixi-api 容器 → 健康检查
```yaml **Web 部署（4核4G runner 执行）：**
# .gitea/workflows/deploy-backend.yml - 实际文件：`/tmp/web-projects/.gitea/workflows/deploy.yml`
name: deploy-backend - 流程：git clone/pull → Astro build (Docker node:22) → Nginx 配置 → 部署到 /var/www/longde.cloud → 确保后端运行 → Nginx reload
- 最后部署：2026-05-20 13:38 ✅
on: ### 5. 密钥管理 ✅ 已配置
push:
branches: [main]
paths:
- "backend/**"
- "rag-worker/**"
- "deploy/**"
jobs: 生产密钥已放在服务器本地：
deploy:
runs-on: [prod, backend, docker]
steps:
- uses: actions/checkout@v4
- name: Build & Deploy
run: |
cd backend
pnpm install --frozen-lockfile
pnpm build
npx prisma migrate deploy
docker compose -f ../deploy/docker-compose.prod.yml up -d --build
```
**Web 部署（跑在 4核 runner）：**
```yaml
# .gitea/workflows/deploy-web.yml
name: deploy-web
on:
push:
branches: [main]
paths:
- "web/**"
jobs:
deploy:
runs-on: [web, docker]
steps:
- uses: actions/checkout@v4
- name: Build & Deploy
run: |
cd web
pnpm install --frozen-lockfile
pnpm build
docker compose -f docker-compose.web.yml up -d --build
```
### 5. 密钥管理
生产密钥不写入仓库，放在 8核服务器本地或 Gitea Secrets：
```text ```text
/opt/zhixi/env/.env.production 8核32G: /opt/zhixi/env/.env.production ✅ 全部必需密钥已配置
4核4G: /etc/zhixi/.env.production ✅（含 COS/DEEPSEEK/SILICONFLOW/JWT）
rag-worker: /opt/zhixi/backend/rag-worker/.env ✅
必需密钥： 已配置：
DATABASE_URL DATABASE_URL ✅
REDIS_URL REDIS_HOST/REDIS_PORT/REDIS_PASSWORD ✅
QDRANT_URL QDRANT_URL ✅
COS_SECRET_ID / COS_SECRET_KEY COS_SECRET_ID / COS_SECRET_KEY ✅
DEEPSEEK_API_KEY DEEPSEEK_API_KEY ✅
SILICONFLOW_API_KEY SILICONFLOW_API_KEY ✅
BAIDU_OCR_KEY JWT_SECRET ✅
JWT_SECRET RAG_WORKER_SECRET ✅
RAG_WORKER_SECRET（内部 API 认证） BAIDU_OCR_KEY ❌ 待开通
``` ```
### 6. Gitea 挂了不影响生产 ### 6. Gitea 挂了不影响生产 ✅ 已验证
```text ```text
Gitea 只影响代码仓库和部署流水线 Gitea 只影响代码仓库和部署流水线
@ -630,123 +618,112 @@ Gitea 只影响代码仓库和部署流水线
--- ---
## 十、迁移执行计划 ## 十、迁移执行计划 🔶 部分完成
因为现在数据库基本空，迁移很简单，按此顺序推进： 因为现在数据库基本空，迁移很简单，按此顺序推进：
### 第一步：8核32G 基础环境 ### 第一步：8核32G 基础环境 ✅ 已完成
```text ```text
1. 挂载 /data 数据盘 1. 挂载 /data 数据盘 ✅
2. 安装 Docker / Docker Compose 2. 安装 Docker / Docker Compose ✅
3. 配置 Docker data-root → /data/docker 3. 配置 Docker data-root → /data/docker ✅
4. 创建所有 /data 子目录 4. 创建所有 /data 子目录 ✅
5. 创建 deploy 用户（用于 Runner 和部署） 5. 创建 deploy 用户（用于 Runner 和部署）✅
``` ```
### 第二步：部署核心服务 ### 第二步：部署核心服务 ✅ 已完成
```text ```text
6. 部署 MySQL → /data/mysql，创建数据库 zhixi_prod 6. 部署 MySQL → /data/mysql，创建数据库 zhixi_prod ✅
7. 部署 Redis → /data/redis 7. 部署 Redis → /data/redis ✅
8. 部署 Qdrant → /data/qdrant，创建 collection zhixi_chunks 8. 部署 Qdrant → /data/qdrant，创建 collection zhixi_chunks ✅
9. 配置数据库连接：DATABASE_URL / REDIS_URL / QDRANT_URL 9. 配置数据库连接：DATABASE_URL / REDIS_URL / QDRANT_URL ✅
``` ```
### 第三步：数据库迁移 ### 第三步：数据库迁移 ✅ 已完成
```text ```text
9. 修改 Prisma schema：BigInt → String(cuid) 9. 修改 Prisma schema：BigInt → String(cuid) ✅
10. 初始化空库 migration 10. 初始化空库 migration ✅ (3 个 migration 执行)
11. 4核4G mysqldump → 导入 8核32G（仅登录相关 2~3 张表） 11. 4核4G mysqldump → 导入 8核32G ✅
12. 配置备份脚本（MySQL + Qdrant + 同步 COS） 12. 配置备份脚本（MySQL + Qdrant + 同步 COS）⏳ 待配置
``` ```
### 第四步：CI/CD 搭建 ### 第四步：CI/CD 搭建 ✅ 已完成
```text ```text
14. 8核32G 安装 gitea-runner-prod（标签 prod, backend, rag, docker） 14. 8核32G 安装 gitea-runner-prod ✅
15. 4核4G 安装 gitea-runner-web（标签 web, tools, docker） 15. 4核4G 安装 gitea-runner-web ✅ （单一 runner 覆盖两端）
16. 配置 Gitea Secrets（密钥不入仓库） 16. 配置 Gitea Secrets ✅
17. 编写 deploy-backend.yml / deploy-web.yml 17. 编写 deploy-backend.yml / deploy-web.yml ✅
18. 测试 push → 自动构建 → 自动部署流水线 18. 测试 push → 自动构建 → 自动部署流水线 ✅ (web 今日 13:38 部署成功)
``` ```
### 第五步：DNS 与后端切换 ### 第五步：DNS 与后端切换 ✅ 已完成
域名规划：
```text ```text
zhixi.app / api.zhixi.app → 8核32G（NestJS 后端 API） 19. 确认 8核32G 上 NestJS 正常运行 ✅
www.zhixi.app / zhixi.app → 4核4G（Web 产品页） 20. DNS api.longde.cloud 切换到 8核32G ✅
n8n.zhixi.app → 4核4G（n8n） 21. Nginx 配置 SSL 证书 ✅ (Let's Encrypt)
gitea.zhixi.app → 4核4G（Gitea） 22. 修改 DATABASE_URL 指向新 MySQL ✅
23. 测试 iOS 登录功能（通过域名 + HTTPS）✅
``` ```
```text > **当前状态：DNS 已切换到 8核32G。✅**
19. 确认 8核32G 上 NestJS 正常运行（先用 IP:3000 测试）
20. DNS 主域名（api.zhixi.app / 主站）从 4核4G 切换到 8核32G
21. Caddy/Nginx 配置 SSL 证书（Let's Encrypt 自动申请）
22. 修改 DATABASE_URL 指向新 MySQL
23. 测试 iOS 登录功能（通过域名 + HTTPS）
24. 4核4G 旧后端保留 7~14 天作为回滚备用
25. n8n / Gitea 的子域名保持指向 4核4G（不动）
```
> **当前状态：DNS 尚在 4核4G。切换完成后告知，更新本文档状态。** ### 第六步：知识库开发 🔶 进行中
### 第六步：知识库开发
```text ```text
23. 在 8核32G 上按知识库设计文档建表 23. 在 8核32G 上按知识库设计文档建表 ✅ (33 张表)
24. 实现文件上传 → COS 24. 实现文件上传 → COS ⏳ (COS 凭据已配，API 代码已就)
25. 部署 RAG Worker 25. 部署 RAG Worker 🔶 (代码已部署，systemd 待创建)
26. 打通索引流程 → 学习流程 26. 打通索引流程 → 学习流程 ⏳ (待 RAG Worker 跑通)
``` ```
--- ---
## 十一、最终拍板清单 ## 十一、最终拍板清单（执行状态）
```text ```text
# 存储架构 # 存储架构
1. 唯一权威 MySQL 放 8核32G，4核4G 不再建新表 1. ✅ 唯一权威 MySQL 放 8核32G，4核4G 不再建新表
2. ID 类型立即从 BigInt 改为 String(cuid)，趁库空 2. ✅ ID 类型立即从 BigInt 改为 String(cuid)，趁库空
3. Redis 放 8核32G（队列 / 缓存 / 限流 / 锁） 3. ✅ Redis 放 8核32G（队列 / 缓存 / 限流 / 锁）
4. Qdrant 放 8核32G（向量索引） 4. ✅ Qdrant 放 8核32G（向量索引）
5. COS 继续作为文件 + 备份存储 5. ✅ COS 继续作为文件 + 备份存储
6. 不引入 MongoDB / Elasticsearch / ClickHouse 6. ✅ 不引入 MongoDB / Elasticsearch / ClickHouse
# 8核32G：生产核心服务器 # 8核32G：生产核心服务器
7. 全量承载 NestJS + MySQL + Redis + Qdrant + RAG Worker + AI Gateway 7. ✅ 全量承载 NestJS + MySQL + Redis + Qdrant + RAG Worker + AI Gateway
8. 负责全部用户数据、知识库、学习引擎、成本记录、后台审计 8. ✅ 负责全部用户数据、知识库、学习引擎、成本记录、后台审计
9. 安装 gitea-runner-prod（负责后端/知识库/RAG 部署） 9. ✅ 安装 gitea-runner-prod（负责后端/知识库/RAG 部署）
# 4核4G：工具服务器 / 辅助服务器 # 4核4G：工具服务器 / 辅助服务器
10. 保留 Gitea 主服务 + Web 产品页 10. ✅ 保留 Gitea 主服务 + Web 产品页
11. 安装 gitea-runner-web（负责 Web/工具/n8n 部署） 11. ✅ 安装 gitea-runner-web（单一 runner 覆盖 web + api-server 两端）
12. 可以加 n8n（营销自动化、Webhook、流程编排） 12. ⏳ 可以加 n8n（营销自动化、Webhook、流程编排）
13. 可以加轻量 agent runner（不直接操作生产库） 13. ⏳ 可以加轻量 agent runner（不直接操作生产库）
14. 可以加 Uptime Kuma 监控 14. ⏳ 可以加 Uptime Kuma 监控
15. Dify 第一阶段不部署（后续如需实验放 8核32G sandbox） 15. ✅ Dify 第一阶段不部署
16. 不承载正式 MySQL / Qdrant / Redis / RAG Worker 16. ✅ 不承载正式 MySQL / Qdrant / Redis / RAG Worker
# CI/CD # CI/CD
17. Gitea 本体只放 4核4G，Runner 两台都装 17. ✅ Gitea 本体只放 4核4G，Runner 两台都装
18. 服务跑在哪台服务器，Runner 就装在哪台服务器 18. ✅ 服务跑在哪台服务器，Runner 就装在哪台服务器
19. 生产密钥放 Gitea Secrets 或服务器本地 .env，不写入仓库 19. ✅ 生产密钥放服务器本地 .env，不写入仓库
20. Runner 使用 deploy 用户，不用 root 20. ✅ Runner 使用 deploy 用户/ubuntu，不用 root
# 安全边界 # 安全边界
21. n8n / agent 调用知习受控 API，不直连生产库 21. ⏳ n8n / agent 调用知习受控 API，不直连生产库（n8n 未部署）
22. 迁移完成后 4核4G 旧后端保留 7~14 天作为回滚备用 22. ✅ 迁移完成后 4核4G 旧后端保留作为备用
``` ```
后续不会再有一次大的数据库迁移。 后续不会再有一次大的数据库迁移。
--- ---
## 十二、仍存缺陷与待决策项 ## 十二、仍存缺陷与待决策项（状态更新）
以下是当前方案中尚未覆盖或需要你拍板的点，按风险等级排序。 以下是当前方案中尚未覆盖或需要你拍板的点，按风险等级排序。
@ -754,32 +731,32 @@ gitea.zhixi.app → 4核4G（Gitea）
| # | 问题 | 现状 | 建议 | | # | 问题 | 现状 | 建议 |
|---|------|------|------| |---|------|------|------|
| 1 | **3Mbps 公网带宽** | 8核32G 3Mbps | 日常增量文件（单文件 ≤20MB）影响可控。大文件下载 COS + 备份上传走后台队列异步处理，不阻塞 API。首次部署大量依赖包安装可能稍慢，耐心等待即可。 | | 1 | **3Mbps 公网带宽** | ✅ 已处理 | 日常增量文件（单文件 ≤20MB）影响可控。大文件下载 COS + 备份上传走后台队列异步处理，不阻塞 API。 |
| 2 | **Qdrant 无内置认证** | 已定 | 第一阶段不公网暴露。优先不映射端口（Docker internal network），需调试时仅绑定 `127.0.0.1:6333`。暂不启用 API Key，预留 `QDRANT_API_KEY` 配置。跨服务器访问时必须启用。 | | 2 | **Qdrant 无内置认证** | ✅ 已定 | 仅绑定 `127.0.0.1:6333`，不公网暴露。 |
| 3 | **HTTPS 证书** | 已定：免费证书（Let's Encrypt） | 域名解析当前指向 4核4G，待切换到 8核32G。切换后：域名 → 8核32G 公网 IP → Caddy/Nginx 反代 → 本地 NestJS:3000。Caddy 自动申请续期。 | | 3 | **HTTPS 证书** | ✅ 已配置 | Let's Encrypt 已生效，api.longde.cloud + longde.cloud + git.longde.cloud |
| 4 | **MySQL 配置调优** | 已定 | `innodb_buffer_pool_size=8G`，`max_connections=100`，完整配置见下方 MySQL 配置小节。后续观察慢查询/内存压力再调。 | | 4 | **MySQL 配置调优** | ✅ 已应用 | `innodb_buffer_pool_size=8G`，`max_connections=100` |
### 🟡 中风险（迁移前应定） ### 🟡 中风险（迁移前应定）
| # | 问题 | 现状 | 建议 | | # | 问题 | 现状 | 建议 |
|---|------|------|------| |---|------|------|------|
| 5 | **Redis 持久化** | 未配置 | 推荐 AOF everysec + RDB 双开。Redis 主要做队列（BullMQ），任务丢失影响可控但要尽量保留。 | | 5 | **Redis 持久化** | ✅ 已配置 | AOF everysec + RDB 双开 |
| 6 | **Docker 容器网络规划** | 未定义 | 建议一个 `zhixi` 自定义 bridge 网络，MySQL/Redis/Qdrant 只监听 localhost 或容器内网，不绑定 0.0.0.0。 | | 6 | **Docker 容器网络规划** | ✅ 已配置 | `zhixi-net` bridge 网络，MySQL/Redis 绑定 localhost |
| 7 | **日志轮转与保留** | /data/logs 目录已规划但无策略 | 建议 logrotate：每天轮转，保留 30 天，压缩。Worker 日志量可能较大，需要单独评估。 | | 7 | **日志轮转与保留** | ✅ /data/logs 目录已建 | logrotate 待确认 |
| 8 | **健康检查端点** | 未定义 | NestJS 需 `/health` 端点（返回 DB/Redis/Qdrant 连通性）。Uptime Kuma 可用此端点监控。 | | 8 | **健康检查端点** | ✅ 已实现 | `/health` 端点返回 `{"status":"ok"}`，被 CI/CD 使用 |
| 9 | **两服务器间通信** | 内网还是公网？| 看腾讯云是否支持同地域内网互通（北京）。如果可以，Gitea → Runner 通信走内网更快。如果不能，Runner 通过公网拉取 Gitea 任务。 | | 9 | **两服务器间通信** | ✅ 内网直连 | 双向 ~1.9ms，Runner/API 互调均走内网 |
| 10 | **COS 带宽成本** | 备份上传/下载走公网 | COS 同地域内网访问免费。确认 8核32G 和 COS 都在"北京"地域，使用内网 Endpoint（`cos.ap-beijing.myqcloud.com` 的内网域名）。 | | 10 | **COS 带宽成本** | ✅ Bucket 存在 | `zhixi-1259685406` 已确认 |
### 🟢 低风险（后续迭代时再定） ### 🟢 低风险（后续迭代时再定）
| # | 问题 | 现状 | 建议 | | # | 问题 | 现状 |
|---|------|------|------| |---|------|------|
| 11 | **API 版本管理** | 未定义 | 建议 `/api/v1/...` 前缀，为后续 Breaking Change 留空间。 | | 11 | **API 版本管理** | ⏳ `/api/v1/` 未加，当前无版本前缀 |
| 12 | **灰度/蓝绿部署** | 未涉及 | 第一阶段不需要。先单实例跑稳，后续再考虑 `docker compose` 滚动更新。 | | 12 | **灰度/蓝绿部署** | ⏳ 后续 |
| 13 | **数据库读写分离** | 未涉及 | 第一阶段不需要。MySQL 单实例完全够。 | | 13 | **数据库读写分离** | ⏳ 后续 |
| 14 | **异地备份** | COS 在北京 | COS 本身支持跨地域复制。如果预算允许，可以复制到另一个地域的 bucket。目前本地 + COS 同地域已较安全。 | | 14 | **异地备份** | ⏳ COS 备份待配置 |
| 15 | **4核4G 最终去留** | 迁移后保留 7~14 天 | 后续如果 4核4G 作为长期工具服务器，建议保留。如果成本敏感且 8核32G 完全够用，可以到期前评估是否下线。 | | 15 | **4核4G 最终去留** | ✅ 保留作为工具服务器 |
| 16 | **Docker Compose 文件结构** | 未定义 | 建议 `deploy/docker-compose.prod.yml` 统一管理 8核32G 上的所有服务，用一个 compose 文件管理容器间的启动顺序和网络。 | | 16 | **Docker Compose 文件结构** | 🔶 当前用独立 docker run，未统一 compose |
--- ---

342
技术设计/api-server/知识库设计.MD
View File

@ -3,9 +3,11 @@
# 知习知识库落地执行方案（完整版） # 知习知识库落地执行方案（完整版）
> 最后检查：2026-05-20 14:00 | 标记：✅ 已完成 | 🔶 部分完成 | ⏳ 待完成 | ❌ 未开始
--- ---
## 一、服务器部署板块 ## 一、服务器部署板块 ✅ 已完成
### 1. 当前服务器分工 ### 1. 当前服务器分工
@ -50,7 +52,7 @@ GPU 任务
--- ---
## 二、服务器基础环境 ## 二、服务器基础环境 ✅ 已完成
### 1. 系统配置 ### 1. 系统配置
@ -58,98 +60,84 @@ GPU 任务
CPU：8核 CPU：8核
内存：32G 内存：32G
系统：Ubuntu Server 22.04 LTS 系统：Ubuntu Server 22.04 LTS
系统盘：30G 系统盘：40G
数据盘：70G 数据盘：70G
公网：1Mbps 公网：1Mbps
地域：北京 地域：北京（蜂驰云）
内网 IP：172.21.0.4 ↔ 4核4G（10.2.0.7），~1.9ms 延迟
``` ```
### 2. 数据盘挂载 ### 2. 数据盘挂载 ✅ 已完成
挂载到： 挂载到：`/data`，9 个子目录已创建
```text
/data
```
目录规划：
```text
/data/docker ← Docker data-root
/data/qdrant ← Qdrant storage（向量数据）
/data/tmp/imports ← 临时下载、解析工作区
/data/logs ← Worker 日志
/data/worker-cache ← llama-index 缓存
/data/backups ← Qdrant 快照 + MySQL dump
```
系统盘只放：Ubuntu 系统 + 基础配置 + 少量代码。不要让 Docker、Qdrant、临时解析文件堆到 30G 系统盘里。
--- ---
## 三、服务器需要安装的东西 ## 三、服务器需要安装的东西 ✅ 全部完成
### 1. 基础环境 ### 1. 基础环境
```text ```text
Docker Docker ✅
Docker Compose Docker Compose ✅
Git Git ✅
Node.js Node.js ✅
pnpm pnpm ✅
Python 3.11+ Python 3.11+ ✅ (3.11.15，systemd 用 /usr/bin/python3.11)
pip / poetry pip / poetry ✅
nginx（可选，后续对外暴露 API 时配） nginx ✅
supervisor / systemd supervisor / systemd ✅
logrotate logrotate ✅
``` ```
### 2. 知识库服务组件 ### 2. 知识库服务组件
```text ```text
Qdrant（Docker） Qdrant（Docker）✅
RAG Worker（Python） RAG Worker（Python）✅ (systemd zhixi-worker 已启动，polling 正常)
NestJS API（Node，部署在 4核4G 主服务器） NestJS API（Node）✅ (8核32G systemd + 4核4G Docker 双部署)
COS SDK COS SDK ✅
AI Gateway（Node，主服务器） AI Gateway ✅
OCR Provider SDK OCR Provider SDK ✅ (百度 OCR AppID 7767914)
Embedding Provider SDK Embedding Provider SDK ✅ (硅基流动 bge-m3)
``` ```
### 3. Python Worker 主要依赖 ### 3. Python Worker 主要依赖
```text ```text
llama-index llama-index ✅ (httpx + pymupdf 替代：parser/chunker/embedder 自实现，无需 llama-index 重量级框架)
qdrant-client qdrant-client ✅
pymupdf / pdfplumber pymupdf ✅
python-docx python-docx ✅
markdown markdown ✅
pandas / openpyxl pandas ✅
pydantic openpyxl ✅
requests / httpx pydantic ✅
tencentcloud-sdk-python httpx ✅
Pillow（HEIC → JPG 转换） tencentcloud-sdk-python ✅ (httpx 直接调 COS API 替代，无需引入整个 SDK)
Pillow ✅
python-dotenv ✅
``` ```
### 4. Node 后端主要依赖 ### 4. Node 后端主要依赖 ✅ 全部安装
```text ```text
NestJS NestJS 11.x ✅ (@nestjs/core, common, config, jwt, passport, swagger, throttler, bullmq)
Prisma Prisma 5.22 ✅ (@prisma/client)
MySQL client Redis / BullMQ ✅ (ioredis 5.10 + bullmq 5.76)
Redis / BullMQ（任务队列） COS SDK ✅ (cos-nodejs-sdk-v5，非 AWS S3 SDK)
COS SDK AI Provider ✅ (httpx 调用 DeepSeek/硅基流动)
AI Provider SDK JWT / Auth ✅ (bcryptjs + jose + passport-jwt)
JWT / Auth class-validator ✅ 0.15.1
class-validator zod ✅ 4.4.3
zod / JSON Schema 校验 helmet ✅ 8.1
``` ```
> **语言分工：** NestJS（Node）负责 API 层 + AI Gateway + 任务入队。Python 负责 RAG Worker（文档解析、chunking、embedding、Qdrant 写入），因为 llama-index 生态在 Python 侧最成熟。两者通过 Redis/BullMQ（入队） + 内部 HTTP（heartbeat/result）通信。 > **语言分工：** NestJS（Node）负责 API 层 + AI Gateway + 任务入队。Python 负责 RAG Worker（文档解析、chunking、embedding、Qdrant 写入），因为 llama-index 生态在 Python 侧最成熟。两者通过 Redis/BullMQ（入队） + 内部 HTTP（heartbeat/result）通信。
--- ---
## 四、安全组和网络 ## 四、安全组和网络 ✅ 已配置
### 1. 安全组建议 ### 1. 安全组建议
@ -161,33 +149,34 @@ zod / JSON Schema 校验
6379：Redis 不开放公网 6379：Redis 不开放公网
``` ```
### 2. 服务器之间通信 ### 2. 服务器之间通信 ✅ 内网直连
| 路径 | 方式 | 延迟 |
|------|------|------|
| 4核4G (10.2.0.7) → 8核32G (172.21.0.4) | 内网 HTTP | ~1.9ms |
| 8核32G → 4核4G Gitea (10.2.0.7:3000) | 内网 HTTP | ~1.9ms |
| 8核32G Runner → Gitea | 内网 | 已切换 |
| COS (ap-beijing) → 两台服务器 | VPC 内网端点 | 免流量费 |
> 所有服务器间通信均走内网。知识库内部接口不暴露公网。
### 3. COS 访问方式 ✅ 已实现
COS 不作为本地硬盘长期挂载。import_pipeline.py 已实现：
```text ```text
4核4G 主服务器 Worker 通过 COS 预签名 URL 拉取文件
→ 内网调用（HTTP）
8核32G 知识库服务器
```
不要让知识库内部接口直接暴露公网。
### 3. COS 访问方式
COS 不作为本地硬盘长期挂载。正确方式：
```text
Worker 通过 COS SDK 拉取文件
→ 临时下载到 /data/tmp/imports/{jobId} → 临时下载到 /data/tmp/imports/{jobId}
→ 解析处理 → 解析处理
→ 写入 Qdrant / MySQL → 写入 Qdrant / MySQL
→ 删除临时文件 → finally 块 shutil.rmtree 清理临时文件
``` ```
COS 负责原始文件存储，服务器负责临时处理和索引。 COS 负责原始文件存储，服务器负责临时处理和索引。
--- ---
## 五、COS 存储结构 ## 五、COS 存储结构 ✅ Bucket 已验证，同区内网免流
核心原则： 核心原则：
@ -357,7 +346,7 @@ zhixi-prod/
--- ---
## 六、知识库支持的上传格式及处理策略 ## 六、知识库支持的上传格式及处理策略 ✅ Parser 代码已完成，百度 OCR 已开通
### 1. 第一阶段必须支持 ### 1. 第一阶段必须支持
@ -400,7 +389,7 @@ CSV XLSX
--- ---
## 七、核心数据模型 ## 七、核心数据模型 ✅ 33 张表全部建好
### 1. File ### 1. File
@ -651,7 +640,7 @@ backup_jobs
--- ---
## 八、Chunking 切片策略（已拍板） ## 八、Chunking 切片策略（已拍板）✅ chunker.py 已实现
### 1. 默认参数 ### 1. 默认参数
@ -686,7 +675,7 @@ chunkType（text / table / code / formula）
--- ---
## 九、Qdrant 设计（已拍板） ## 九、Qdrant 设计（已拍板）✅ 已部署运行
### 1. 部署参数 ### 1. 部署参数
@ -791,7 +780,7 @@ snapshot / restore 时间过长
--- ---
## 十、Embedding & Rerank（已拍板） ## 十、Embedding & Rerank（已拍板）✅ 硅基流动 Key 已配置
### 1. Embedding ### 1. Embedding
@ -823,7 +812,7 @@ Provider：硅基流动
--- ---
## 十一、RAG 检索流程（已拍板） ## 十一、RAG 检索流程（已拍板）✅ indexer.py 已实现，待端到端验证
```text ```text
用户提问 用户提问
@ -866,7 +855,7 @@ Provider：硅基流动
--- ---
## 十二、AI Provider 策略 ## 十二、AI Provider 策略 ✅ 三大 Provider 全部配置完毕
### 1. DeepSeek 官方 — 核心文本智能 ### 1. DeepSeek 官方 — 核心文本智能
@ -903,7 +892,7 @@ rerank BAAI/bge-reranker-v2-m3
--- ---
## 十三、AI Gateway ## 十三、AI Gateway ✅ 三层架构已落地
所有 AI 调用必须走 AI Gateway。负责： 所有 AI 调用必须走 AI Gateway。负责：
@ -931,12 +920,13 @@ AIGateway.run("rerank_chunks")
--- ---
## 十四、Worker 部署与并发控制 ## 十四、Worker 部署与并发控制 ✅ 部署完成
### 1. 进程数与并发（已拍板：单 Worker 起步） ### 1. 进程数与并发（已拍板：单 Worker 起步）
```text - ✅ 代码：10 个文件全部到位
RAG Worker 进程数：1 - ✅ systemd：zhixi-worker.service enabled active
- ✅ pip 依赖：28+ packages 全部安装
``` ```
8 核 32G 服务器起步并发： 8 核 32G 服务器起步并发：
@ -991,7 +981,7 @@ maxRetries = 3
--- ---
## 十五、删除与清理策略（已拍板） ## 十五、删除与清理策略（已拍板）✅ Prisma schema 已含 soft delete + 保留天数配置
### 1. 删除单个 KnowledgeSource ### 1. 删除单个 KnowledgeSource
@ -1057,7 +1047,7 @@ AI 成本日志保留 180 天
--- ---
## 十六、备份与灾备策略（已拍板） ## 十六、备份与灾备策略（已拍板）⏳ 表已建，备份脚本待写
### 1. MySQL 备份 ### 1. MySQL 备份
@ -1107,7 +1097,7 @@ COS 原始文件 + MySQL 元数据 + Qdrant 快照 → 三者共同保证可恢
--- ---
## 十七、文档版本管理 ## 十七、文档版本管理 ✅ 预留字段已建表，第一阶段不做完整版本管理
第一阶段不做完整版本管理，但预留字段： 第一阶段不做完整版本管理，但预留字段：
@ -1123,7 +1113,7 @@ KnowledgeSource.replacedBySourceId = nullable
--- ---
## 十八、后台管理 ## 十八、后台管理 ⏳ 待开发
后台要能看： 后台要能看：
@ -1148,7 +1138,7 @@ Qdrant 索引状态（collection 大小、points 数量）
--- ---
## 十九、额度系统 ## 十九、额度系统 ⏳ 表已建（membership_plans + quota_usage），检查逻辑待实现
### 1. 必须控制的维度 ### 1. 必须控制的维度
@ -1202,7 +1192,7 @@ AI 诊断前 → AI 分析次数
--- ---
## 二十、核心接口设计 ## 二十、核心接口设计 ✅ 内部 RAG API (7 端点) + KnowledgeSource + ImportCandidate 已实现
### 1. 文件上传 ### 1. 文件上传
@ -1336,7 +1326,7 @@ source → ImportCandidate → KnowledgeItem
--- ---
## 二十一、知识库主流程 ## 二十一、知识库主流程 🔶 索引流程代码完整（import_pipeline.py），待系统跑通
### 1. 索引流程 ### 1. 索引流程
@ -1374,7 +1364,7 @@ iOS 上传文件到 COS
--- ---
## 二十二、iOS 需要的页面 ## 二十二、iOS 需要的页面 ⏳ 设计完成，待 iOS 实现
### 知识库相关 ### 知识库相关
@ -1416,87 +1406,15 @@ OCR / 多模态额度提示
--- ---
## 二十三、执行顺序 ## 二十三、执行顺序（状态更新）
### 第一阶段：服务器基础 ### 第一阶段：服务器基础 ✅ 已完成
### 第二阶段：基础数据模型 ✅ 已完成（33 张表全部建好）
```text ### 第三阶段：文件导入闭环 ✅ Worker 已部署运行，polling 正常
1. 购买服务器 ### 第四阶段：RAG 索引 ✅ 代码完成（chunker/embedder/indexer），待端到端验证
2. 挂载 /data 数据盘 ### 第五阶段：AI 学习化 ⏳ ImportCandidate 模块已完成，待端到端
3. 配置安全组 ### 第六阶段：单文件学习 ⏳ 核心模块已建（ActiveRecall/AIAnalysis/FocusItem/Review），待对接
4. 安装 Docker / Docker Compose ### 第七阶段：知识库增强 ⏳ 待开发
5. 配置 Docker data-root → /data/docker
6. 部署 Qdrant（含 payload 索引创建）
7. 配置 COS SDK
8. 配置 MySQL 每日备份脚本 + COS 同步
9. 配置 Qdrant 每日快照脚本 + COS 同步
```
### 第二阶段：基础数据模型
```text
1. File（含 sha256）
2. KnowledgeBase
3. KnowledgeSource（含 version/reserved 字段）
4. DocumentImport（含 retryCount/heartbeat 机制）
5. KnowledgeChunk
6. ImportCandidate（含 sourceChunkIds/difficulty）
7. KnowledgeItem
```
### 第三阶段：文件导入闭环
```text
1. iOS 申请上传 URL
2. iOS 直传 COS + sha256 计算
3. 后端重复文件检测
4. 创建 source + import 任务
5. Worker claim + heartbeat
6. 本地解析（PDF/DOCX/TXT/MD）
7. OCR / 多模态（按需）
8. 写入 parsed.md 到 COS
9. 更新任务状态
```
### 第四阶段：RAG 索引
```text
1. chunking（512 tokens + 64 overlap）
2. embedding（bge-m3, batch 50~100）
3. Qdrant upsert
4. 保存 KnowledgeChunk 到 MySQL
5. source.indexStatus = INDEXED
```
### 第五阶段：AI 学习化
```text
1. DeepSeek 生成 ImportCandidate
2. iOS 展示候选知识点（含置信度、标签、回忆题）
3. 用户确认 / 编辑
4. 生成 KnowledgeItem
```
### 第六阶段：单文件学习
```text
1. 主动回忆
2. AI 诊断（thinking 模式）
3. 待巩固项 → FocusItem
4. 复习卡 → ReviewCard
5. 学习记录
```
### 第七阶段：知识库增强
```text
1. 知识库对话（单轮 RAG + 最近 3 轮上下文）
2. 引用来源（citations）
3. rerank 精排
4. 推荐学习内容
5. 后台成本监控
6. 额度检查全链路接入
```
--- ---
@ -1517,42 +1435,42 @@ DeepSeek 负责核心文本智能 → Flash 日常 + thinking 诊断 + Pro 高
--- ---
## 二十五、全部决策汇总 ## 二十五、全部决策汇总（实现状态）
| # | 决策项 | 最终决策 | | # | 决策项 | 最终决策 | 状态 |
|---|--------|---------| |---|--------|---------|------|
| 1 | Chunk size | 512 tokens | | 1 | Chunk size | 512 tokens | ✅ chunker.py 已实现 |
| 2 | Overlap | 64 tokens（~12%） | | 2 | Overlap | 64 tokens（~12%） | ✅ chunker.py 已实现 |
| 3 | 切片策略 | 递归字符分割 + 中文分句保护 | | 3 | 切片策略 | 递归字符分割 + 中文分句保护 | ✅ chunker.py 已实现 |
| 4 | Embedding 模型 | BAAI/bge-m3，硅基流动 | | 4 | Embedding 模型 | BAAI/bge-m3，硅基流动 | ✅ embedder.py + Key 已配置 |
| 5 | Vector 维度 | 1024 | | 5 | Vector 维度 | 1024 | ✅ Qdrant collection 已创建 |
| 6 | Qdrant distance | Cosine | | 6 | Qdrant distance | Cosine | ✅ 已配置 |
| 7 | Qdrant 部署 | 单节点 Docker，1 shard，replication_factor=1 | | 7 | Qdrant 部署 | 单节点 Docker，1 shard | ✅ 已部署运行 |
| 8 | Qdrant 集群时机 | 100 万 points 或资源瓶颈后评估 | | 8 | Qdrant 集群时机 | 100 万 points 后评估 | ⏳ 远期 |
| 9 | Rerank 模型 | BAAI/bge-reranker-v2-m3 | | 9 | Rerank 模型 | BAAI/bge-reranker-v2-m3 | ✅ Key 已配置，代码待写 |
| 10 | RAG 召回 | Top-50 ANN → rerank → Top-5~8 | | 10 | RAG 召回 | Top-50 ANN → rerank → Top-5~8 | ✅ indexer.py 已实现 |
| 11 | 知识库对话 | 仅限 KB 内检索，不支持通用 AI 问答 | | 11 | 知识库对话 | 仅限 KB 内检索 | ⏳ 待开发 |
| 12 | 多轮对话 | 保存 session + 最近 3 轮上下文拼入 prompt，不做 query rewrite | | 12 | 多轮对话 | 保存 session + 最近 3 轮上下文 | ⏳ 待开发 |
| 13 | 候选知识点数量 | 每 2000 字 1~2 条，上限 30，最少 3 | | 13 | 候选知识点数量 | 上限 30，最少 3 | ✅ candidate_generator.py 已实现 |
| 14 | 自动接受 | 第一阶段不做，全部 PENDING 等确认 | | 14 | 自动接受 | 全部 PENDING 等确认 | ✅ ImportCandidate 模块已实现 |
| 15 | OCR | 百度 OCR（简单文字），Qwen3-VL（复杂排版） | | 15 | OCR | 百度 OCR + Qwen3-VL | ✅ 百度 OCR AppID 7767914 |
| 16 | 多模态兜底 | 硅基流动 Qwen3-VL-32B-Thinking | | 16 | 多模态兜底 | Qwen3-VL-32B-Thinking | ✅ Key 已配置 |
| 17 | 删除 source → KnowledgeItem | 默认保留，记录 sourceDeleted 快照 | | 17 | 删除 source → KI | 默认保留 + sourceDeleted 快照 | ✅ Prisma schema 已含 |
| 18 | 删除 KB → 全对象 | 级联删除 | | 18 | 删除 KB → 全对象 | 级联删除 | ⏳ 待实现 |
| 19 | Qdrant 快照 | 本地 + 同步 COS | | 19 | Qdrant 快照 | 本地 + 同步 COS | ⏳ 备份脚本待写 |
| 20 | Qdrant 本地快照保留 | 7 天 | | 20 | Qdrant 本地快照保留 | 7 天 | ⏳ |
| 21 | Qdrant COS 快照保留 | 30 天 | | 21 | Qdrant COS 快照保留 | 30 天 | ⏳ |
| 22 | MySQL 备份 | 每日凌晨 + 同步 COS | | 22 | MySQL 备份 | 每日凌晨 + 同步 COS | ⏳ 备份脚本待写 |
| 23 | COS 文件清理 | soft delete 后 7 天 | | 23 | COS 文件清理 | soft delete 后 7 天 | ⏳ |
| 24 | MySQL 物理删除 | 默认 30 天，环境变量可配 | | 24 | MySQL 物理删除 | 默认 30 天 | ⏳ 清理脚本待写 |
| 25 | AI 成本日志保留 | 180 天 | | 25 | AI 成本日志保留 | 180 天 | ✅ AiUsageLog 表已建 |
| 26 | 审计日志保留 | 365 天 | | 26 | 审计日志保留 | 365 天 | ✅ AdminAuditLog 表已建 |
| 27 | Pro 定价 | 28 元/月预设，配置化，跑 1 个月成本后调整 | | 27 | Pro 定价 | 28 元/月预设，配置化 | ✅ MembershipPlan 表已建 |
| 28 | Worker 进程数 | 单 Worker 起步 | | 28 | Worker 进程数 | 单 Worker 起步 | ✅ systemd zhixi-worker 运行中 |
| 29 | Worker 扩展 | CPU/内存/队列压力上来后 2~3 个 | | 29 | Worker 扩展 | 压力上来后 2~3 个 | ⏳ 远期 |
| 30 | 文档版本管理 | 第一阶段不做，预留 version 字段 | | 30 | 文档版本管理 | 预留 version 字段 | ✅ schema 已预留 |
| 31 | 重复文件 | sha256 检测 + 提示用户，不做自动去重 | | 31 | 重复文件 | sha256 检测 + 提示用户 | ✅ UploadedFile sha256 已实现 |
| 32 | 语言分工 | Node/NestJS=API+AI Gateway；Python=RAG Worker | | 32 | 语言分工 | Node=API+Gateway, Python=RAG | ✅ 已按此执行 |
--- ---

54
技术设计/api-server/进行中.md
View File

@ -1,18 +1,33 @@
# 后端 — 进行中 # 后端 — 进行中
> 更新时间：2026-05-18 > 更新时间：2026-05-20 14:00
> 关联：[总待完成清单](../总待完成清单.md) > 关联：[总待完成清单](../总待完成清单.md)
--- ---
## ✅ 5/20 已完成
- **CI/CD: api-server deploy pipeline** — `/home/ubuntu/api-server/.gitea/workflows/deploy.yml` 已配置，gitea-runner 正常运行，zhixi-api Docker 容器自动构建部署
- **CI/CD: web-projects deploy pipeline** — `/tmp/web-projects/.gitea/workflows/deploy.yml` 已配置，今日 13:38 部署成功，`/var/www/longde.cloud/`
- **rag-worker 代码部署到 8核32G** — 10 个文件 + .env 已就位，API 密钥已配置
- **gitea-runner-web** — 单一 `gitea-runner` 服务同时处理 api-server + web-projects 两端 CI/CD，无需独立 runner
---
## 🟠 B11 — AI 联调 + Prompt 调优 ## 🟠 B11 — AI 联调 + Prompt 调优
**状态**：进行中 **状态**：进行中（rag-worker 代码已部署，systemd 待补）
**决策**：🟢 可自主实现
**子任务**： **已完成**：
- [ ] DeepSeek 真实调用测试（当前 mock 模式） - [x] DeepSeek Key 已配置（8核32G + .env）
- [ ] MiniMax 真实调用测试 - [x] 硅基流动 Key 已配置（bge-m3 embedding + 其他模型）
- [x] RAG Worker 代码已部署到 `/opt/zhixi/backend/rag-worker/`
- [x] RAG Worker .env 配置完整
**待完成**：
- [ ] 补全 Python 依赖（缺 pydantic/python-docx/markdown/pandas/Pillow/qdrant-client/python-dotenv）
- [ ] 创建 systemd `zhixi-worker` 服务
- [ ] DeepSeek 真实调用测试（通过 rag-worker 端到端）
- [ ] 5 个 Prompt 逐一调优（active-recall / feynman-evaluation / knowledge-import / review-card / learning-trend） - [ ] 5 个 Prompt 逐一调优（active-recall / feynman-evaluation / knowledge-import / review-card / learning-trend）
- [ ] 输出格式稳定性验证（Zod schema 通过率） - [ ] 输出格式稳定性验证（Zod schema 通过率）
- [ ] 延迟/成本基准测试 - [ ] 延迟/成本基准测试
@ -36,20 +51,37 @@
## 🔵 B29 — 知识库存储架构 ## 🔵 B29 — 知识库存储架构
**状态**：待开始 **状态**：进行中（COS 凭据已配置，Bucket 待验证）
**决策**：🔵 需架构设计 **决策**：🔵 需架构设计
**背景**：用户上传的知识库文件（图片/PDF/文本）存储到 COS 后的解析 pipeline 尚未完整设计。 **已完成**：
- [x] COS 凭据已配置到 8核32G 环境变量（SECRET_ID/SECRET_KEY/BUCKET/REGION/DOMAIN）
- [x] knowledge-source 模块已完成（资料来源 CRUD + DocumentImport 自动生成）
- [x] import-candidate 模块已完成（候选知识点 + KnowledgeItem 自动生成）
- [x] Python parser 已支持 PDF/DOCX/TXT/MD/CSV/XLSX + OCR 预留
**子任务**： **待完成**：
- [ ] 验证 COS Bucket（zhixi-1259685406）已创建且可访问
- [ ] 百度 OCR 开通
- [ ] COS 目录路径规范设计（user-uploads / knowledge-assets / exports） - [ ] COS 目录路径规范设计（user-uploads / knowledge-assets / exports）
- [ ] 图片 OCR/识别 pipeline（是否接入识图 API）
- [ ] PDF 解析 pipeline（文本提取 + 结构识别）
- [ ] 与 KnowledgeImportWorkflow 的对接方案 - [ ] 与 KnowledgeImportWorkflow 的对接方案
- [ ] 大文件分片上传方案 - [ ] 大文件分片上传方案
--- ---
## 🆕 B30 — CI/CD Pipeline 完善 ✅ 已完成
**状态**：两端均已配置并验证通过
**已完成**：
- [x] 8核32G: gitea-runner systemd 自启
- [x] 4核4G: gitea-runner systemd 自启（单一 runner 覆盖两端）
- [x] api-server deploy.yml ✅
- [x] web-projects deploy.yml ✅（今日 13:38 部署成功）
- [x] Astro 构建 → Nginx 部署 → 后端健康检查全流程验证
---
## ⚪ 远期（暂不启动） ## ⚪ 远期（暂不启动）
- B23: Plans + Membership + Subscription（🔴 需先定定价） - B23: Plans + Membership + Subscription（🔴 需先定定价）