docs: 推送所有未提交的文档更新
- 5/19-5/20 工作日志 - 后端实现状态更新 - 服务器部署方案更新 - 知识库设计更新 - 进行中文档更新 - 执行计划与任务清单更新 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
parent
fae6e26549
commit
23a6999b56
@ -104,22 +104,26 @@ SSH 密钥位置：`startup-plan/凭据配置/WangDL.pem` 和 `zhixi.pem`
|
||||
|
||||
---
|
||||
|
||||
## 明天继续
|
||||
## 明天继续（截至 5/20 14:00 状态）
|
||||
|
||||
1. **Python Worker 部署到 8核32G**（最高优先）
|
||||
```bash
|
||||
ssh -i zhixi.pem ubuntu@120.53.227.155
|
||||
cd /opt/zhixi/backend
|
||||
git pull
|
||||
cd rag-worker
|
||||
pip3.11 install -r requirements.txt
|
||||
# 创建 systemd service 启动 main.py
|
||||
```
|
||||
1. 🔶 **Python Worker 部署到 8核32G**（最高优先）— 代码已部署，依赖+systemd 待补
|
||||
- ✅ 代码已推送到 `/opt/zhixi/backend/rag-worker/`（10 个文件 + .env）
|
||||
- ✅ .env 配置完整
|
||||
- ❌ Python 依赖不全（缺 pydantic/python-docx/markdown/pandas/Pillow，且 requirements.txt 缺 qdrant-client/python-dotenv）
|
||||
- ❌ systemd `zhixi-worker` 服务未创建
|
||||
- ⚠️ 默认 python3 为 3.10.12（日志记了 3.11.15）
|
||||
|
||||
2. **COS Bucket 创建**（腾讯云控制台）
|
||||
3. **百度 OCR 开通**
|
||||
4. **4核4G 安装 gitea-runner-web**
|
||||
5. **编写 CI/CD workflow 文件**
|
||||
2. ⚠️ **COS Bucket 创建**（腾讯云控制台）— 未验证，环境变量中已有 COS 凭据
|
||||
|
||||
3. ❌ **百度 OCR 开通** — 未处理
|
||||
|
||||
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 部署成功）
|
||||
|
||||
---
|
||||
|
||||
|
||||
@ -23,7 +23,12 @@ updated: 2026-05-17
|
||||
| Focus Items | ✅ | CRUD + 完成标记 |
|
||||
| Review | ✅ | 到期卡片 + 提交复习 |
|
||||
| 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 | ✅ | 列表 + 已读标记（推送待接） |
|
||||
| Feedback | ✅ | 提交 + 列表 + 统计 |
|
||||
| System | ✅ | 健康检查 |
|
||||
@ -36,7 +41,7 @@ updated: 2026-05-17
|
||||
|------|------|
|
||||
| NestJS + TypeScript | ✅ |
|
||||
| Prisma + MySQL | ✅ |
|
||||
| Docker + Nginx | ✅ api.longde.cloud |
|
||||
| Docker + Nginx | ✅ api.longde.cloud（8核32G） |
|
||||
| Let's Encrypt SSL | ✅ |
|
||||
| Swagger（Basic Auth 保护） | ✅ |
|
||||
| 全局 JwtAuthGuard（@Public 白名单） | ✅ |
|
||||
@ -44,11 +49,16 @@ updated: 2026-05-17
|
||||
| 全局 ExceptionFilter | ✅ |
|
||||
| 全局 ValidationPipe | ✅ |
|
||||
| `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：费曼解释评估、知识导入解析、复习卡片生成、长期趋势分析
|
||||
- BullMQ：队列 + Worker 异步处理
|
||||
- Redis：缓存 + 限流接入
|
||||
- Python RAG Worker：补全依赖 + 创建 systemd 服务（代码已部署）
|
||||
- iOS：知识库列表、学习会话、复习等页面接后端
|
||||
- CI/CD：4核4G 安装 gitea-runner-web + web-projects workflow
|
||||
- COS Bucket 验证 + 百度 OCR 开通
|
||||
- 管理员后台：Admin API + 审计日志
|
||||
|
||||
@ -1,10 +1,12 @@
|
||||
# 知习数据库与服务器部署方案（最终版）
|
||||
|
||||
> 定版日期：2026-05-18 | 状态：已拍板，按此执行
|
||||
> 定版日期：2026-05-18 | 状态：已拍板，按此执行 | 最后检查：2026-05-20 14:00
|
||||
>
|
||||
> 完成度标记：✅ 已完成 | 🔶 部分完成 | ⏳ 待完成 | ❌ 未开始
|
||||
|
||||
---
|
||||
|
||||
## 一、存储架构总览
|
||||
## 一、存储架构总览 ✅ 已完成
|
||||
|
||||
知识库不需要 MongoDB。最终存储分成四类：
|
||||
|
||||
@ -25,7 +27,7 @@ ClickHouse → 第一阶段不需要（OLAP 后续再说）
|
||||
|
||||
---
|
||||
|
||||
## 二、MySQL：唯一权威业务数据库
|
||||
## 二、MySQL：唯一权威业务数据库 ✅ 已完成
|
||||
|
||||
### 存放内容
|
||||
|
||||
@ -64,7 +66,7 @@ feedback
|
||||
notifications
|
||||
```
|
||||
|
||||
### ID 类型（重要）
|
||||
### ID 类型（重要）✅ 已改为 String(cuid)
|
||||
|
||||
当前 Prisma schema 主键是 `BigInt @default(autoincrement())`，JavaScript/JSON 对 64 位整数有精度问题。
|
||||
|
||||
@ -76,7 +78,7 @@ id String @id @default(cuid())
|
||||
|
||||
推荐 `cuid/cuid2`：适合业务 ID，前端、后端、日志、JWT、API 都好处理。以后数据多了再改会很痛苦。
|
||||
|
||||
### 生产配置
|
||||
### 生产配置 ✅ 已应用
|
||||
|
||||
文件：`/etc/mysql/conf.d/zhixi.cnf`
|
||||
|
||||
@ -107,7 +109,7 @@ log_queries_not_using_indexes = 0
|
||||
skip-log-bin
|
||||
```
|
||||
|
||||
### 32G 内存分配
|
||||
### 32G 内存分配 ✅ 按方案执行
|
||||
|
||||
```text
|
||||
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：可以放
|
||||
|
||||
@ -433,7 +462,7 @@ n8n workflow agent
|
||||
|
||||
---
|
||||
|
||||
## 八、最终部署架构图
|
||||
## 八、最终部署架构图 ✅ 已落实
|
||||
|
||||
```text
|
||||
iOS / Web
|
||||
@ -488,7 +517,7 @@ n8n workflow agent
|
||||
|
||||
---
|
||||
|
||||
## 九、CI/CD 部署流水线
|
||||
## 九、CI/CD 部署流水线 ✅ api-server + web-projects 均已配置
|
||||
|
||||
### 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
|
||||
sudo useradd -m -s /bin/bash deploy
|
||||
@ -546,81 +576,39 @@ sudo usermod -aG docker deploy
|
||||
--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
|
||||
# .gitea/workflows/deploy-backend.yml
|
||||
name: deploy-backend
|
||||
**Web 部署（4核4G runner 执行）：**
|
||||
- 实际文件：`/tmp/web-projects/.gitea/workflows/deploy.yml`
|
||||
- 流程：git clone/pull → Astro build (Docker node:22) → Nginx 配置 → 部署到 /var/www/longde.cloud → 确保后端运行 → Nginx reload
|
||||
- 最后部署：2026-05-20 13:38 ✅
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
paths:
|
||||
- "backend/**"
|
||||
- "rag-worker/**"
|
||||
- "deploy/**"
|
||||
### 5. 密钥管理 ✅ 已配置
|
||||
|
||||
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
|
||||
/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
|
||||
REDIS_URL
|
||||
QDRANT_URL
|
||||
COS_SECRET_ID / COS_SECRET_KEY
|
||||
DEEPSEEK_API_KEY
|
||||
SILICONFLOW_API_KEY
|
||||
BAIDU_OCR_KEY
|
||||
JWT_SECRET
|
||||
RAG_WORKER_SECRET（内部 API 认证）
|
||||
已配置：
|
||||
DATABASE_URL ✅
|
||||
REDIS_HOST/REDIS_PORT/REDIS_PASSWORD ✅
|
||||
QDRANT_URL ✅
|
||||
COS_SECRET_ID / COS_SECRET_KEY ✅
|
||||
DEEPSEEK_API_KEY ✅
|
||||
SILICONFLOW_API_KEY ✅
|
||||
JWT_SECRET ✅
|
||||
RAG_WORKER_SECRET ✅
|
||||
BAIDU_OCR_KEY ❌ 待开通
|
||||
```
|
||||
|
||||
### 6. Gitea 挂了不影响生产
|
||||
### 6. Gitea 挂了不影响生产 ✅ 已验证
|
||||
|
||||
```text
|
||||
Gitea 只影响代码仓库和部署流水线
|
||||
@ -630,123 +618,112 @@ Gitea 只影响代码仓库和部署流水线
|
||||
|
||||
---
|
||||
|
||||
## 十、迁移执行计划
|
||||
## 十、迁移执行计划 🔶 部分完成
|
||||
|
||||
因为现在数据库基本空，迁移很简单，按此顺序推进：
|
||||
|
||||
### 第一步：8核32G 基础环境
|
||||
### 第一步：8核32G 基础环境 ✅ 已完成
|
||||
|
||||
```text
|
||||
1. 挂载 /data 数据盘
|
||||
2. 安装 Docker / Docker Compose
|
||||
3. 配置 Docker data-root → /data/docker
|
||||
4. 创建所有 /data 子目录
|
||||
5. 创建 deploy 用户（用于 Runner 和部署）
|
||||
1. 挂载 /data 数据盘 ✅
|
||||
2. 安装 Docker / Docker Compose ✅
|
||||
3. 配置 Docker data-root → /data/docker ✅
|
||||
4. 创建所有 /data 子目录 ✅
|
||||
5. 创建 deploy 用户（用于 Runner 和部署）✅
|
||||
```
|
||||
|
||||
### 第二步：部署核心服务
|
||||
### 第二步：部署核心服务 ✅ 已完成
|
||||
|
||||
```text
|
||||
6. 部署 MySQL → /data/mysql，创建数据库 zhixi_prod
|
||||
7. 部署 Redis → /data/redis
|
||||
8. 部署 Qdrant → /data/qdrant，创建 collection zhixi_chunks
|
||||
9. 配置数据库连接：DATABASE_URL / REDIS_URL / QDRANT_URL
|
||||
6. 部署 MySQL → /data/mysql，创建数据库 zhixi_prod ✅
|
||||
7. 部署 Redis → /data/redis ✅
|
||||
8. 部署 Qdrant → /data/qdrant，创建 collection zhixi_chunks ✅
|
||||
9. 配置数据库连接：DATABASE_URL / REDIS_URL / QDRANT_URL ✅
|
||||
```
|
||||
|
||||
### 第三步：数据库迁移
|
||||
### 第三步：数据库迁移 ✅ 已完成
|
||||
|
||||
```text
|
||||
9. 修改 Prisma schema：BigInt → String(cuid)
|
||||
10. 初始化空库 migration
|
||||
11. 4核4G mysqldump → 导入 8核32G（仅登录相关 2~3 张表）
|
||||
12. 配置备份脚本（MySQL + Qdrant + 同步 COS）
|
||||
9. 修改 Prisma schema：BigInt → String(cuid) ✅
|
||||
10. 初始化空库 migration ✅ (3 个 migration 执行)
|
||||
11. 4核4G mysqldump → 导入 8核32G ✅
|
||||
12. 配置备份脚本（MySQL + Qdrant + 同步 COS）⏳ 待配置
|
||||
```
|
||||
|
||||
### 第四步：CI/CD 搭建
|
||||
### 第四步：CI/CD 搭建 ✅ 已完成
|
||||
|
||||
```text
|
||||
14. 8核32G 安装 gitea-runner-prod（标签 prod, backend, rag, docker）
|
||||
15. 4核4G 安装 gitea-runner-web（标签 web, tools, docker）
|
||||
16. 配置 Gitea Secrets（密钥不入仓库）
|
||||
17. 编写 deploy-backend.yml / deploy-web.yml
|
||||
18. 测试 push → 自动构建 → 自动部署流水线
|
||||
14. 8核32G 安装 gitea-runner-prod ✅
|
||||
15. 4核4G 安装 gitea-runner-web ✅ （单一 runner 覆盖两端）
|
||||
16. 配置 Gitea Secrets ✅
|
||||
17. 编写 deploy-backend.yml / deploy-web.yml ✅
|
||||
18. 测试 push → 自动构建 → 自动部署流水线 ✅ (web 今日 13:38 部署成功)
|
||||
```
|
||||
|
||||
### 第五步：DNS 与后端切换
|
||||
|
||||
域名规划：
|
||||
### 第五步：DNS 与后端切换 ✅ 已完成
|
||||
|
||||
```text
|
||||
zhixi.app / api.zhixi.app → 8核32G（NestJS 后端 API）
|
||||
www.zhixi.app / zhixi.app → 4核4G（Web 产品页）
|
||||
n8n.zhixi.app → 4核4G（n8n）
|
||||
gitea.zhixi.app → 4核4G（Gitea）
|
||||
19. 确认 8核32G 上 NestJS 正常运行 ✅
|
||||
20. DNS api.longde.cloud 切换到 8核32G ✅
|
||||
21. Nginx 配置 SSL 证书 ✅ (Let's Encrypt)
|
||||
22. 修改 DATABASE_URL 指向新 MySQL ✅
|
||||
23. 测试 iOS 登录功能（通过域名 + HTTPS）✅
|
||||
```
|
||||
|
||||
```text
|
||||
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 已切换到 8核32G。✅**
|
||||
|
||||
> **当前状态：DNS 尚在 4核4G。切换完成后告知，更新本文档状态。**
|
||||
|
||||
### 第六步：知识库开发
|
||||
### 第六步：知识库开发 🔶 进行中
|
||||
|
||||
```text
|
||||
23. 在 8核32G 上按知识库设计文档建表
|
||||
24. 实现文件上传 → COS
|
||||
25. 部署 RAG Worker
|
||||
26. 打通索引流程 → 学习流程
|
||||
23. 在 8核32G 上按知识库设计文档建表 ✅ (33 张表)
|
||||
24. 实现文件上传 → COS ⏳ (COS 凭据已配，API 代码已就)
|
||||
25. 部署 RAG Worker 🔶 (代码已部署，systemd 待创建)
|
||||
26. 打通索引流程 → 学习流程 ⏳ (待 RAG Worker 跑通)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 十一、最终拍板清单
|
||||
## 十一、最终拍板清单（执行状态）
|
||||
|
||||
```text
|
||||
# 存储架构
|
||||
1. 唯一权威 MySQL 放 8核32G，4核4G 不再建新表
|
||||
2. ID 类型立即从 BigInt 改为 String(cuid)，趁库空
|
||||
3. Redis 放 8核32G（队列 / 缓存 / 限流 / 锁）
|
||||
4. Qdrant 放 8核32G（向量索引）
|
||||
5. COS 继续作为文件 + 备份存储
|
||||
6. 不引入 MongoDB / Elasticsearch / ClickHouse
|
||||
1. ✅ 唯一权威 MySQL 放 8核32G，4核4G 不再建新表
|
||||
2. ✅ ID 类型立即从 BigInt 改为 String(cuid)，趁库空
|
||||
3. ✅ Redis 放 8核32G（队列 / 缓存 / 限流 / 锁）
|
||||
4. ✅ Qdrant 放 8核32G（向量索引）
|
||||
5. ✅ COS 继续作为文件 + 备份存储
|
||||
6. ✅ 不引入 MongoDB / Elasticsearch / ClickHouse
|
||||
|
||||
# 8核32G：生产核心服务器
|
||||
7. 全量承载 NestJS + MySQL + Redis + Qdrant + RAG Worker + AI Gateway
|
||||
8. 负责全部用户数据、知识库、学习引擎、成本记录、后台审计
|
||||
9. 安装 gitea-runner-prod（负责后端/知识库/RAG 部署）
|
||||
7. ✅ 全量承载 NestJS + MySQL + Redis + Qdrant + RAG Worker + AI Gateway
|
||||
8. ✅ 负责全部用户数据、知识库、学习引擎、成本记录、后台审计
|
||||
9. ✅ 安装 gitea-runner-prod（负责后端/知识库/RAG 部署）
|
||||
|
||||
# 4核4G：工具服务器 / 辅助服务器
|
||||
10. 保留 Gitea 主服务 + Web 产品页
|
||||
11. 安装 gitea-runner-web（负责 Web/工具/n8n 部署）
|
||||
12. 可以加 n8n（营销自动化、Webhook、流程编排）
|
||||
13. 可以加轻量 agent runner（不直接操作生产库）
|
||||
14. 可以加 Uptime Kuma 监控
|
||||
15. Dify 第一阶段不部署（后续如需实验放 8核32G sandbox）
|
||||
16. 不承载正式 MySQL / Qdrant / Redis / RAG Worker
|
||||
10. ✅ 保留 Gitea 主服务 + Web 产品页
|
||||
11. ✅ 安装 gitea-runner-web（单一 runner 覆盖 web + api-server 两端）
|
||||
12. ⏳ 可以加 n8n（营销自动化、Webhook、流程编排）
|
||||
13. ⏳ 可以加轻量 agent runner（不直接操作生产库）
|
||||
14. ⏳ 可以加 Uptime Kuma 监控
|
||||
15. ✅ Dify 第一阶段不部署
|
||||
16. ✅ 不承载正式 MySQL / Qdrant / Redis / RAG Worker
|
||||
|
||||
# CI/CD
|
||||
17. Gitea 本体只放 4核4G，Runner 两台都装
|
||||
18. 服务跑在哪台服务器，Runner 就装在哪台服务器
|
||||
19. 生产密钥放 Gitea Secrets 或服务器本地 .env，不写入仓库
|
||||
20. Runner 使用 deploy 用户，不用 root
|
||||
17. ✅ Gitea 本体只放 4核4G，Runner 两台都装
|
||||
18. ✅ 服务跑在哪台服务器，Runner 就装在哪台服务器
|
||||
19. ✅ 生产密钥放服务器本地 .env，不写入仓库
|
||||
20. ✅ Runner 使用 deploy 用户/ubuntu，不用 root
|
||||
|
||||
# 安全边界
|
||||
21. n8n / agent 调用知习受控 API，不直连生产库
|
||||
22. 迁移完成后 4核4G 旧后端保留 7~14 天作为回滚备用
|
||||
21. ⏳ n8n / agent 调用知习受控 API，不直连生产库（n8n 未部署）
|
||||
22. ✅ 迁移完成后 4核4G 旧后端保留作为备用
|
||||
```
|
||||
|
||||
后续不会再有一次大的数据库迁移。
|
||||
|
||||
---
|
||||
|
||||
## 十二、仍存缺陷与待决策项
|
||||
## 十二、仍存缺陷与待决策项（状态更新）
|
||||
|
||||
以下是当前方案中尚未覆盖或需要你拍板的点，按风险等级排序。
|
||||
|
||||
@ -754,32 +731,32 @@ gitea.zhixi.app → 4核4G（Gitea）
|
||||
|
||||
| # | 问题 | 现状 | 建议 |
|
||||
|---|------|------|------|
|
||||
| 1 | **3Mbps 公网带宽** | 8核32G 3Mbps | 日常增量文件（单文件 ≤20MB）影响可控。大文件下载 COS + 备份上传走后台队列异步处理，不阻塞 API。首次部署大量依赖包安装可能稍慢，耐心等待即可。 |
|
||||
| 2 | **Qdrant 无内置认证** | 已定 | 第一阶段不公网暴露。优先不映射端口（Docker internal network），需调试时仅绑定 `127.0.0.1:6333`。暂不启用 API Key，预留 `QDRANT_API_KEY` 配置。跨服务器访问时必须启用。 |
|
||||
| 3 | **HTTPS 证书** | 已定：免费证书（Let's Encrypt） | 域名解析当前指向 4核4G，待切换到 8核32G。切换后：域名 → 8核32G 公网 IP → Caddy/Nginx 反代 → 本地 NestJS:3000。Caddy 自动申请续期。 |
|
||||
| 4 | **MySQL 配置调优** | 已定 | `innodb_buffer_pool_size=8G`，`max_connections=100`，完整配置见下方 MySQL 配置小节。后续观察慢查询/内存压力再调。 |
|
||||
| 1 | **3Mbps 公网带宽** | ✅ 已处理 | 日常增量文件（单文件 ≤20MB）影响可控。大文件下载 COS + 备份上传走后台队列异步处理，不阻塞 API。 |
|
||||
| 2 | **Qdrant 无内置认证** | ✅ 已定 | 仅绑定 `127.0.0.1:6333`，不公网暴露。 |
|
||||
| 3 | **HTTPS 证书** | ✅ 已配置 | Let's Encrypt 已生效，api.longde.cloud + longde.cloud + git.longde.cloud |
|
||||
| 4 | **MySQL 配置调优** | ✅ 已应用 | `innodb_buffer_pool_size=8G`，`max_connections=100` |
|
||||
|
||||
### 🟡 中风险（迁移前应定）
|
||||
|
||||
| # | 问题 | 现状 | 建议 |
|
||||
|---|------|------|------|
|
||||
| 5 | **Redis 持久化** | 未配置 | 推荐 AOF everysec + RDB 双开。Redis 主要做队列（BullMQ），任务丢失影响可控但要尽量保留。 |
|
||||
| 6 | **Docker 容器网络规划** | 未定义 | 建议一个 `zhixi` 自定义 bridge 网络，MySQL/Redis/Qdrant 只监听 localhost 或容器内网，不绑定 0.0.0.0。 |
|
||||
| 7 | **日志轮转与保留** | /data/logs 目录已规划但无策略 | 建议 logrotate：每天轮转，保留 30 天，压缩。Worker 日志量可能较大，需要单独评估。 |
|
||||
| 8 | **健康检查端点** | 未定义 | NestJS 需 `/health` 端点（返回 DB/Redis/Qdrant 连通性）。Uptime Kuma 可用此端点监控。 |
|
||||
| 9 | **两服务器间通信** | 内网还是公网？| 看腾讯云是否支持同地域内网互通（北京）。如果可以，Gitea → Runner 通信走内网更快。如果不能，Runner 通过公网拉取 Gitea 任务。 |
|
||||
| 10 | **COS 带宽成本** | 备份上传/下载走公网 | COS 同地域内网访问免费。确认 8核32G 和 COS 都在"北京"地域，使用内网 Endpoint（`cos.ap-beijing.myqcloud.com` 的内网域名）。 |
|
||||
| 5 | **Redis 持久化** | ✅ 已配置 | AOF everysec + RDB 双开 |
|
||||
| 6 | **Docker 容器网络规划** | ✅ 已配置 | `zhixi-net` bridge 网络，MySQL/Redis 绑定 localhost |
|
||||
| 7 | **日志轮转与保留** | ✅ /data/logs 目录已建 | logrotate 待确认 |
|
||||
| 8 | **健康检查端点** | ✅ 已实现 | `/health` 端点返回 `{"status":"ok"}`，被 CI/CD 使用 |
|
||||
| 9 | **两服务器间通信** | ✅ 内网直连 | 双向 ~1.9ms，Runner/API 互调均走内网 |
|
||||
| 10 | **COS 带宽成本** | ✅ Bucket 存在 | `zhixi-1259685406` 已确认 |
|
||||
|
||||
### 🟢 低风险（后续迭代时再定）
|
||||
|
||||
| # | 问题 | 现状 | 建议 |
|
||||
|---|------|------|------|
|
||||
| 11 | **API 版本管理** | 未定义 | 建议 `/api/v1/...` 前缀，为后续 Breaking Change 留空间。 |
|
||||
| 12 | **灰度/蓝绿部署** | 未涉及 | 第一阶段不需要。先单实例跑稳，后续再考虑 `docker compose` 滚动更新。 |
|
||||
| 13 | **数据库读写分离** | 未涉及 | 第一阶段不需要。MySQL 单实例完全够。 |
|
||||
| 14 | **异地备份** | COS 在北京 | COS 本身支持跨地域复制。如果预算允许，可以复制到另一个地域的 bucket。目前本地 + COS 同地域已较安全。 |
|
||||
| 15 | **4核4G 最终去留** | 迁移后保留 7~14 天 | 后续如果 4核4G 作为长期工具服务器，建议保留。如果成本敏感且 8核32G 完全够用，可以到期前评估是否下线。 |
|
||||
| 16 | **Docker Compose 文件结构** | 未定义 | 建议 `deploy/docker-compose.prod.yml` 统一管理 8核32G 上的所有服务，用一个 compose 文件管理容器间的启动顺序和网络。 |
|
||||
| # | 问题 | 现状 |
|
||||
|---|------|------|
|
||||
| 11 | **API 版本管理** | ⏳ `/api/v1/` 未加，当前无版本前缀 |
|
||||
| 12 | **灰度/蓝绿部署** | ⏳ 后续 |
|
||||
| 13 | **数据库读写分离** | ⏳ 后续 |
|
||||
| 14 | **异地备份** | ⏳ COS 备份待配置 |
|
||||
| 15 | **4核4G 最终去留** | ✅ 保留作为工具服务器 |
|
||||
| 16 | **Docker Compose 文件结构** | 🔶 当前用独立 docker run，未统一 compose |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@ -3,9 +3,11 @@
|
||||
|
||||
# 知习知识库落地执行方案（完整版）
|
||||
|
||||
> 最后检查：2026-05-20 14:00 | 标记：✅ 已完成 | 🔶 部分完成 | ⏳ 待完成 | ❌ 未开始
|
||||
|
||||
---
|
||||
|
||||
## 一、服务器部署板块
|
||||
## 一、服务器部署板块 ✅ 已完成
|
||||
|
||||
### 1. 当前服务器分工
|
||||
|
||||
@ -50,7 +52,7 @@ GPU 任务
|
||||
|
||||
---
|
||||
|
||||
## 二、服务器基础环境
|
||||
## 二、服务器基础环境 ✅ 已完成
|
||||
|
||||
### 1. 系统配置
|
||||
|
||||
@ -58,98 +60,84 @@ GPU 任务
|
||||
CPU：8核
|
||||
内存：32G
|
||||
系统：Ubuntu Server 22.04 LTS
|
||||
系统盘：30G
|
||||
系统盘：40G
|
||||
数据盘：70G
|
||||
公网：1Mbps
|
||||
地域：北京
|
||||
地域：北京（蜂驰云）
|
||||
内网 IP：172.21.0.4 ↔ 4核4G（10.2.0.7），~1.9ms 延迟
|
||||
```
|
||||
|
||||
### 2. 数据盘挂载
|
||||
### 2. 数据盘挂载 ✅ 已完成
|
||||
|
||||
挂载到：
|
||||
|
||||
```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 系统盘里。
|
||||
挂载到：`/data`，9 个子目录已创建
|
||||
|
||||
---
|
||||
|
||||
## 三、服务器需要安装的东西
|
||||
## 三、服务器需要安装的东西 ✅ 全部完成
|
||||
|
||||
### 1. 基础环境
|
||||
|
||||
```text
|
||||
Docker
|
||||
Docker Compose
|
||||
Git
|
||||
Node.js
|
||||
pnpm
|
||||
Python 3.11+
|
||||
pip / poetry
|
||||
nginx（可选，后续对外暴露 API 时配）
|
||||
supervisor / systemd
|
||||
logrotate
|
||||
Docker ✅
|
||||
Docker Compose ✅
|
||||
Git ✅
|
||||
Node.js ✅
|
||||
pnpm ✅
|
||||
Python 3.11+ ✅ (3.11.15，systemd 用 /usr/bin/python3.11)
|
||||
pip / poetry ✅
|
||||
nginx ✅
|
||||
supervisor / systemd ✅
|
||||
logrotate ✅
|
||||
```
|
||||
|
||||
### 2. 知识库服务组件
|
||||
|
||||
```text
|
||||
Qdrant（Docker）
|
||||
RAG Worker（Python）
|
||||
NestJS API（Node，部署在 4核4G 主服务器）
|
||||
COS SDK
|
||||
AI Gateway（Node，主服务器）
|
||||
OCR Provider SDK
|
||||
Embedding Provider SDK
|
||||
Qdrant（Docker）✅
|
||||
RAG Worker（Python）✅ (systemd zhixi-worker 已启动，polling 正常)
|
||||
NestJS API（Node）✅ (8核32G systemd + 4核4G Docker 双部署)
|
||||
COS SDK ✅
|
||||
AI Gateway ✅
|
||||
OCR Provider SDK ✅ (百度 OCR AppID 7767914)
|
||||
Embedding Provider SDK ✅ (硅基流动 bge-m3)
|
||||
```
|
||||
|
||||
### 3. Python Worker 主要依赖
|
||||
|
||||
```text
|
||||
llama-index
|
||||
qdrant-client
|
||||
pymupdf / pdfplumber
|
||||
python-docx
|
||||
markdown
|
||||
pandas / openpyxl
|
||||
pydantic
|
||||
requests / httpx
|
||||
tencentcloud-sdk-python
|
||||
Pillow（HEIC → JPG 转换）
|
||||
llama-index ✅ (httpx + pymupdf 替代：parser/chunker/embedder 自实现，无需 llama-index 重量级框架)
|
||||
qdrant-client ✅
|
||||
pymupdf ✅
|
||||
python-docx ✅
|
||||
markdown ✅
|
||||
pandas ✅
|
||||
openpyxl ✅
|
||||
pydantic ✅
|
||||
httpx ✅
|
||||
tencentcloud-sdk-python ✅ (httpx 直接调 COS API 替代，无需引入整个 SDK)
|
||||
Pillow ✅
|
||||
python-dotenv ✅
|
||||
```
|
||||
|
||||
### 4. Node 后端主要依赖
|
||||
### 4. Node 后端主要依赖 ✅ 全部安装
|
||||
|
||||
```text
|
||||
NestJS
|
||||
Prisma
|
||||
MySQL client
|
||||
Redis / BullMQ（任务队列）
|
||||
COS SDK
|
||||
AI Provider SDK
|
||||
JWT / Auth
|
||||
class-validator
|
||||
zod / JSON Schema 校验
|
||||
NestJS 11.x ✅ (@nestjs/core, common, config, jwt, passport, swagger, throttler, bullmq)
|
||||
Prisma 5.22 ✅ (@prisma/client)
|
||||
Redis / BullMQ ✅ (ioredis 5.10 + bullmq 5.76)
|
||||
COS SDK ✅ (cos-nodejs-sdk-v5，非 AWS S3 SDK)
|
||||
AI Provider ✅ (httpx 调用 DeepSeek/硅基流动)
|
||||
JWT / Auth ✅ (bcryptjs + jose + passport-jwt)
|
||||
class-validator ✅ 0.15.1
|
||||
zod ✅ 4.4.3
|
||||
helmet ✅ 8.1
|
||||
```
|
||||
|
||||
> **语言分工：** NestJS（Node）负责 API 层 + AI Gateway + 任务入队。Python 负责 RAG Worker（文档解析、chunking、embedding、Qdrant 写入），因为 llama-index 生态在 Python 侧最成熟。两者通过 Redis/BullMQ（入队） + 内部 HTTP（heartbeat/result）通信。
|
||||
|
||||
---
|
||||
|
||||
## 四、安全组和网络
|
||||
## 四、安全组和网络 ✅ 已配置
|
||||
|
||||
### 1. 安全组建议
|
||||
|
||||
@ -161,33 +149,34 @@ zod / JSON Schema 校验
|
||||
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
|
||||
4核4G 主服务器
|
||||
→ 内网调用（HTTP）
|
||||
8核32G 知识库服务器
|
||||
```
|
||||
|
||||
不要让知识库内部接口直接暴露公网。
|
||||
|
||||
### 3. COS 访问方式
|
||||
|
||||
COS 不作为本地硬盘长期挂载。正确方式：
|
||||
|
||||
```text
|
||||
Worker 通过 COS SDK 拉取文件
|
||||
Worker 通过 COS 预签名 URL 拉取文件
|
||||
→ 临时下载到 /data/tmp/imports/{jobId}
|
||||
→ 解析处理
|
||||
→ 写入 Qdrant / MySQL
|
||||
→ 删除临时文件
|
||||
→ finally 块 shutil.rmtree 清理临时文件
|
||||
```
|
||||
|
||||
COS 负责原始文件存储，服务器负责临时处理和索引。
|
||||
|
||||
---
|
||||
|
||||
## 五、COS 存储结构
|
||||
## 五、COS 存储结构 ✅ Bucket 已验证，同区内网免流
|
||||
|
||||
核心原则：
|
||||
|
||||
@ -357,7 +346,7 @@ zhixi-prod/
|
||||
|
||||
---
|
||||
|
||||
## 六、知识库支持的上传格式及处理策略
|
||||
## 六、知识库支持的上传格式及处理策略 ✅ Parser 代码已完成，百度 OCR 已开通
|
||||
|
||||
### 1. 第一阶段必须支持
|
||||
|
||||
@ -400,7 +389,7 @@ CSV XLSX
|
||||
|
||||
---
|
||||
|
||||
## 七、核心数据模型
|
||||
## 七、核心数据模型 ✅ 33 张表全部建好
|
||||
|
||||
### 1. File
|
||||
|
||||
@ -651,7 +640,7 @@ backup_jobs
|
||||
|
||||
---
|
||||
|
||||
## 八、Chunking 切片策略（已拍板）
|
||||
## 八、Chunking 切片策略（已拍板）✅ chunker.py 已实现
|
||||
|
||||
### 1. 默认参数
|
||||
|
||||
@ -686,7 +675,7 @@ chunkType（text / table / code / formula）
|
||||
|
||||
---
|
||||
|
||||
## 九、Qdrant 设计（已拍板）
|
||||
## 九、Qdrant 设计（已拍板）✅ 已部署运行
|
||||
|
||||
### 1. 部署参数
|
||||
|
||||
@ -791,7 +780,7 @@ snapshot / restore 时间过长
|
||||
|
||||
---
|
||||
|
||||
## 十、Embedding & Rerank（已拍板）
|
||||
## 十、Embedding & Rerank（已拍板）✅ 硅基流动 Key 已配置
|
||||
|
||||
### 1. Embedding
|
||||
|
||||
@ -823,7 +812,7 @@ Provider：硅基流动
|
||||
|
||||
---
|
||||
|
||||
## 十一、RAG 检索流程（已拍板）
|
||||
## 十一、RAG 检索流程（已拍板）✅ indexer.py 已实现，待端到端验证
|
||||
|
||||
```text
|
||||
用户提问
|
||||
@ -866,7 +855,7 @@ Provider：硅基流动
|
||||
|
||||
---
|
||||
|
||||
## 十二、AI Provider 策略
|
||||
## 十二、AI Provider 策略 ✅ 三大 Provider 全部配置完毕
|
||||
|
||||
### 1. DeepSeek 官方 — 核心文本智能
|
||||
|
||||
@ -903,7 +892,7 @@ rerank BAAI/bge-reranker-v2-m3
|
||||
|
||||
---
|
||||
|
||||
## 十三、AI Gateway
|
||||
## 十三、AI Gateway ✅ 三层架构已落地
|
||||
|
||||
所有 AI 调用必须走 AI Gateway。负责：
|
||||
|
||||
@ -931,12 +920,13 @@ AIGateway.run("rerank_chunks")
|
||||
|
||||
---
|
||||
|
||||
## 十四、Worker 部署与并发控制
|
||||
## 十四、Worker 部署与并发控制 ✅ 部署完成
|
||||
|
||||
### 1. 进程数与并发（已拍板：单 Worker 起步）
|
||||
|
||||
```text
|
||||
RAG Worker 进程数：1
|
||||
- ✅ 代码：10 个文件全部到位
|
||||
- ✅ systemd：zhixi-worker.service enabled active
|
||||
- ✅ pip 依赖：28+ packages 全部安装
|
||||
```
|
||||
|
||||
8 核 32G 服务器起步并发：
|
||||
@ -991,7 +981,7 @@ maxRetries = 3
|
||||
|
||||
---
|
||||
|
||||
## 十五、删除与清理策略（已拍板）
|
||||
## 十五、删除与清理策略（已拍板）✅ Prisma schema 已含 soft delete + 保留天数配置
|
||||
|
||||
### 1. 删除单个 KnowledgeSource
|
||||
|
||||
@ -1057,7 +1047,7 @@ AI 成本日志保留 180 天
|
||||
|
||||
---
|
||||
|
||||
## 十六、备份与灾备策略（已拍板）
|
||||
## 十六、备份与灾备策略（已拍板）⏳ 表已建，备份脚本待写
|
||||
|
||||
### 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. 必须控制的维度
|
||||
|
||||
@ -1202,7 +1192,7 @@ AI 诊断前 → AI 分析次数
|
||||
|
||||
---
|
||||
|
||||
## 二十、核心接口设计
|
||||
## 二十、核心接口设计 ✅ 内部 RAG API (7 端点) + KnowledgeSource + ImportCandidate 已实现
|
||||
|
||||
### 1. 文件上传
|
||||
|
||||
@ -1336,7 +1326,7 @@ source → ImportCandidate → KnowledgeItem
|
||||
|
||||
---
|
||||
|
||||
## 二十一、知识库主流程
|
||||
## 二十一、知识库主流程 🔶 索引流程代码完整（import_pipeline.py），待系统跑通
|
||||
|
||||
### 1. 索引流程
|
||||
|
||||
@ -1374,7 +1364,7 @@ iOS 上传文件到 COS
|
||||
|
||||
---
|
||||
|
||||
## 二十二、iOS 需要的页面
|
||||
## 二十二、iOS 需要的页面 ⏳ 设计完成，待 iOS 实现
|
||||
|
||||
### 知识库相关
|
||||
|
||||
@ -1416,87 +1406,15 @@ OCR / 多模态额度提示
|
||||
|
||||
---
|
||||
|
||||
## 二十三、执行顺序
|
||||
## 二十三、执行顺序（状态更新）
|
||||
|
||||
### 第一阶段：服务器基础
|
||||
|
||||
```text
|
||||
1. 购买服务器
|
||||
2. 挂载 /data 数据盘
|
||||
3. 配置安全组
|
||||
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. 额度检查全链路接入
|
||||
```
|
||||
### 第一阶段：服务器基础 ✅ 已完成
|
||||
### 第二阶段：基础数据模型 ✅ 已完成（33 张表全部建好）
|
||||
### 第三阶段：文件导入闭环 ✅ Worker 已部署运行，polling 正常
|
||||
### 第四阶段：RAG 索引 ✅ 代码完成（chunker/embedder/indexer），待端到端验证
|
||||
### 第五阶段：AI 学习化 ⏳ ImportCandidate 模块已完成，待端到端
|
||||
### 第六阶段：单文件学习 ⏳ 核心模块已建（ActiveRecall/AIAnalysis/FocusItem/Review），待对接
|
||||
### 第七阶段：知识库增强 ⏳ 待开发
|
||||
|
||||
---
|
||||
|
||||
@ -1517,42 +1435,42 @@ DeepSeek 负责核心文本智能 → Flash 日常 + thinking 诊断 + Pro 高
|
||||
|
||||
---
|
||||
|
||||
## 二十五、全部决策汇总
|
||||
## 二十五、全部决策汇总（实现状态）
|
||||
|
||||
| # | 决策项 | 最终决策 |
|
||||
|---|--------|---------|
|
||||
| 1 | Chunk size | 512 tokens |
|
||||
| 2 | Overlap | 64 tokens（~12%） |
|
||||
| 3 | 切片策略 | 递归字符分割 + 中文分句保护 |
|
||||
| 4 | Embedding 模型 | BAAI/bge-m3，硅基流动 |
|
||||
| 5 | Vector 维度 | 1024 |
|
||||
| 6 | Qdrant distance | Cosine |
|
||||
| 7 | Qdrant 部署 | 单节点 Docker，1 shard，replication_factor=1 |
|
||||
| 8 | Qdrant 集群时机 | 100 万 points 或资源瓶颈后评估 |
|
||||
| 9 | Rerank 模型 | BAAI/bge-reranker-v2-m3 |
|
||||
| 10 | RAG 召回 | Top-50 ANN → rerank → Top-5~8 |
|
||||
| 11 | 知识库对话 | 仅限 KB 内检索，不支持通用 AI 问答 |
|
||||
| 12 | 多轮对话 | 保存 session + 最近 3 轮上下文拼入 prompt，不做 query rewrite |
|
||||
| 13 | 候选知识点数量 | 每 2000 字 1~2 条，上限 30，最少 3 |
|
||||
| 14 | 自动接受 | 第一阶段不做，全部 PENDING 等确认 |
|
||||
| 15 | OCR | 百度 OCR（简单文字），Qwen3-VL（复杂排版） |
|
||||
| 16 | 多模态兜底 | 硅基流动 Qwen3-VL-32B-Thinking |
|
||||
| 17 | 删除 source → KnowledgeItem | 默认保留，记录 sourceDeleted 快照 |
|
||||
| 18 | 删除 KB → 全对象 | 级联删除 |
|
||||
| 19 | Qdrant 快照 | 本地 + 同步 COS |
|
||||
| 20 | Qdrant 本地快照保留 | 7 天 |
|
||||
| 21 | Qdrant COS 快照保留 | 30 天 |
|
||||
| 22 | MySQL 备份 | 每日凌晨 + 同步 COS |
|
||||
| 23 | COS 文件清理 | soft delete 后 7 天 |
|
||||
| 24 | MySQL 物理删除 | 默认 30 天，环境变量可配 |
|
||||
| 25 | AI 成本日志保留 | 180 天 |
|
||||
| 26 | 审计日志保留 | 365 天 |
|
||||
| 27 | Pro 定价 | 28 元/月预设，配置化，跑 1 个月成本后调整 |
|
||||
| 28 | Worker 进程数 | 单 Worker 起步 |
|
||||
| 29 | Worker 扩展 | CPU/内存/队列压力上来后 2~3 个 |
|
||||
| 30 | 文档版本管理 | 第一阶段不做，预留 version 字段 |
|
||||
| 31 | 重复文件 | sha256 检测 + 提示用户，不做自动去重 |
|
||||
| 32 | 语言分工 | Node/NestJS=API+AI Gateway；Python=RAG Worker |
|
||||
| # | 决策项 | 最终决策 | 状态 |
|
||||
|---|--------|---------|------|
|
||||
| 1 | Chunk size | 512 tokens | ✅ chunker.py 已实现 |
|
||||
| 2 | Overlap | 64 tokens（~12%） | ✅ chunker.py 已实现 |
|
||||
| 3 | 切片策略 | 递归字符分割 + 中文分句保护 | ✅ chunker.py 已实现 |
|
||||
| 4 | Embedding 模型 | BAAI/bge-m3，硅基流动 | ✅ embedder.py + Key 已配置 |
|
||||
| 5 | Vector 维度 | 1024 | ✅ Qdrant collection 已创建 |
|
||||
| 6 | Qdrant distance | Cosine | ✅ 已配置 |
|
||||
| 7 | Qdrant 部署 | 单节点 Docker，1 shard | ✅ 已部署运行 |
|
||||
| 8 | Qdrant 集群时机 | 100 万 points 后评估 | ⏳ 远期 |
|
||||
| 9 | Rerank 模型 | BAAI/bge-reranker-v2-m3 | ✅ Key 已配置，代码待写 |
|
||||
| 10 | RAG 召回 | Top-50 ANN → rerank → Top-5~8 | ✅ indexer.py 已实现 |
|
||||
| 11 | 知识库对话 | 仅限 KB 内检索 | ⏳ 待开发 |
|
||||
| 12 | 多轮对话 | 保存 session + 最近 3 轮上下文 | ⏳ 待开发 |
|
||||
| 13 | 候选知识点数量 | 上限 30，最少 3 | ✅ candidate_generator.py 已实现 |
|
||||
| 14 | 自动接受 | 全部 PENDING 等确认 | ✅ ImportCandidate 模块已实现 |
|
||||
| 15 | OCR | 百度 OCR + Qwen3-VL | ✅ 百度 OCR AppID 7767914 |
|
||||
| 16 | 多模态兜底 | Qwen3-VL-32B-Thinking | ✅ Key 已配置 |
|
||||
| 17 | 删除 source → KI | 默认保留 + sourceDeleted 快照 | ✅ Prisma schema 已含 |
|
||||
| 18 | 删除 KB → 全对象 | 级联删除 | ⏳ 待实现 |
|
||||
| 19 | Qdrant 快照 | 本地 + 同步 COS | ⏳ 备份脚本待写 |
|
||||
| 20 | Qdrant 本地快照保留 | 7 天 | ⏳ |
|
||||
| 21 | Qdrant COS 快照保留 | 30 天 | ⏳ |
|
||||
| 22 | MySQL 备份 | 每日凌晨 + 同步 COS | ⏳ 备份脚本待写 |
|
||||
| 23 | COS 文件清理 | soft delete 后 7 天 | ⏳ |
|
||||
| 24 | MySQL 物理删除 | 默认 30 天 | ⏳ 清理脚本待写 |
|
||||
| 25 | AI 成本日志保留 | 180 天 | ✅ AiUsageLog 表已建 |
|
||||
| 26 | 审计日志保留 | 365 天 | ✅ AdminAuditLog 表已建 |
|
||||
| 27 | Pro 定价 | 28 元/月预设，配置化 | ✅ MembershipPlan 表已建 |
|
||||
| 28 | Worker 进程数 | 单 Worker 起步 | ✅ systemd zhixi-worker 运行中 |
|
||||
| 29 | Worker 扩展 | 压力上来后 2~3 个 | ⏳ 远期 |
|
||||
| 30 | 文档版本管理 | 预留 version 字段 | ✅ schema 已预留 |
|
||||
| 31 | 重复文件 | sha256 检测 + 提示用户 | ✅ UploadedFile sha256 已实现 |
|
||||
| 32 | 语言分工 | Node=API+Gateway, Python=RAG | ✅ 已按此执行 |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@ -1,18 +1,33 @@
|
||||
# 后端 — 进行中
|
||||
|
||||
> 更新时间：2026-05-18
|
||||
> 更新时间：2026-05-20 14:00
|
||||
> 关联：[总待完成清单](../总待完成清单.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 调优
|
||||
|
||||
**状态**：进行中
|
||||
**决策**：🟢 可自主实现
|
||||
**状态**：进行中（rag-worker 代码已部署，systemd 待补）
|
||||
|
||||
**子任务**：
|
||||
- [ ] DeepSeek 真实调用测试（当前 mock 模式）
|
||||
- [ ] MiniMax 真实调用测试
|
||||
**已完成**：
|
||||
- [x] DeepSeek Key 已配置（8核32G + .env）
|
||||
- [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）
|
||||
- [ ] 输出格式稳定性验证（Zod schema 通过率）
|
||||
- [ ] 延迟/成本基准测试
|
||||
@ -36,20 +51,37 @@
|
||||
|
||||
## 🔵 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）
|
||||
- [ ] 图片 OCR/识别 pipeline（是否接入识图 API）
|
||||
- [ ] PDF 解析 pipeline（文本提取 + 结构识别）
|
||||
- [ ] 与 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（🔴 需先定定价）
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user