知习 API Server

AI-first 系统化学习平台后端，NestJS 11 + TypeScript。

架构

Nginx (:80/:443)
  └── /api/* → NestJS API (:3000)

┌─────────────────────────────────────┐
│  API 进程 (main.ts)                  │
│  - REST API (50+ 业务模块)            │
│  - Swagger (/api-docs)               │
│  - Admin API (/admin-api/*)          │
│  - Internal API (/internal/*)        │
└─────────────────────────────────────┘

┌─────────────────────────────────────┐
│  Worker 进程 (worker.main.ts)        │
│  - BullMQ 队列消费                    │
│  - AI 分析 / 文档导入 / 通知          │
└─────────────────────────────────────┘

┌──────────┬──────────┬──────────┬──────────┐
│  MySQL 8 │  Redis 7 │  Qdrant  │  COS     │
└──────────┴──────────┴──────────┴──────────┘

技术栈

类别	技术
框架	NestJS 11
语言	TypeScript
ORM	Prisma 5
数据库	MySQL 8.0
缓存/队列	Redis 7 + BullMQ
向量库	Qdrant
对象存储	腾讯云 COS（支持 local 模式）
AI	DeepSeek API + SiliconFlow Embedding
认证	JWT (用户) + JWT (管理员) + Internal API Key + httpOnly Cookie (Admin)
文档	Swagger (开发默认开启，生产 Basic Auth)

快速开始

# 1. 安装依赖
npm install

# 2. 启动基础设施（OrbStack Docker）
docker compose -f docker-compose.local.yml up -d

# 3. 初始化数据库
npx prisma migrate deploy

# 4. 配置环境变量
cp .env.example .env.local
# 编辑 .env.local

# 5. 启动 API（开发模式）
npm run start:dev          # → http://localhost:3000

# 6. 启动 Worker（另一个终端）
npm run start:worker

基础设施（docker-compose.local.yml）

服务	端口	说明
MySQL 8.0	127.0.0.1:3306	zhixi_prod 数据库
Redis 7	127.0.0.1:6379	BullMQ + 缓存
Qdrant	127.0.0.1:6333	向量检索

环境变量

变量	必需	说明
DATABASE_URL	✅	MySQL 连接字符串
REDIS_HOST	✅	Redis 地址
REDIS_PORT	✅	Redis 端口
REDIS_PASSWORD	否	Redis 密码
JWT_SECRET	✅	用户 JWT 密钥
ADMIN_JWT_ACCESS_SECRET	✅	管理员 JWT 密钥
ADMIN_JWT_REFRESH_SECRET	否	管理员刷新密钥
INTERNAL_API_KEY	✅	Worker 内部调用密钥
CREDENTIAL_ENCRYPTION_KEY	✅	凭据加密密钥
DEEPSEEK_API_KEY	否	DeepSeek API Key
SILICONFLOW_API_KEY	否	SiliconFlow Embedding Key
QDRANT_URL	否	Qdrant 地址
STORAGE_DRIVER	否	cos 或 local（默认）
COS_SECRET_ID	否	腾讯云 COS SecretId
COS_SECRET_KEY	否	腾讯云 COS SecretKey
COS_BUCKET	否	COS Bucket 名称
COS_REGION	否	COS 区域
ENABLE_SWAGGER	否	生产环境启用 Swagger
SWAGGER_USER	否	Swagger Basic Auth 用户名
SWAGGER_PASSWORD	否	Swagger Basic Auth 密码

完整配置参考 .env.example。

模块清单（50+）

用户端 API

模块	路由前缀	说明
auth	/api/auth	用户认证（登录/注册/刷新/登出/Apple）
users	/api/users	用户管理
knowledge-base	/api/knowledge-bases	知识库 CRUD
ai	/api/ai	AI 对话/分析
ai-analysis	/api/ai-analysis	AI 分析结果
ai-job	—	AI 作业调度（Worker）
ai-runtime	—	AI 运行时（Worker）
active-recall	/api/active-recall	主动回忆
review	/api/review	间隔重复复习
quiz	/api/quiz	测验
focus-items	/api/focus-items	待巩固项
learning-session	/api/learning-session	学习会话
learning-activity	/api/learning-activity	学习活跃统计
document-import	/api/document-import	文档导入
rag-chat	/api/rag/chat	RAG 知识库对话
notifications	/api/notifications	通知
feedback	/api/feedback	用户反馈
waitlist	/api/waitlist	等待名单
membership	/api/membership	会员/订阅
files	/api/files	文件管理
workspace	/api/workspace	工作区
content-safety	—	内容安全检测
secrets	—	密钥管理

管理端 API

模块	路由前缀	说明
admin-auth	/admin-api/auth	管理员认证（登录/刷新/登出）
admin-users	/admin-api/admin-users	管理员 CRUD
dashboard	/admin-api/dashboard	数据看板
audit	/admin-api/audit	审计日志
billing	/admin-api/billing	API 用量/成本
config	/admin-api/config	系统配置
servers	/admin-api/servers	服务器监控
ai-gateway	/admin-api/ai-gateway	AI 网关路由
compliance	/admin-api/compliance	合规安全
release	/admin-api/release	发布决策
learning	/admin-api/learning	学习数据总览
imports	/admin-api/imports	文档导入监控
notifications-admin	/admin-api/notifications	通知管理
backup	/admin-api/backup	备份清理
vector	/admin-api/vector	向量检索
metrics	/admin-api/metrics	接口监控
throttle	/admin-api/throttle	限流管理

内部 API（Worker 调用）

路由	说明
POST /internal/rag/jobs/next	获取下一个导入任务
POST /internal/rag/jobs/:id/claim	认领任务
POST /internal/rag/jobs/:id/heartbeat	心跳
POST /internal/rag/jobs/:id/status	更新状态
POST /internal/rag/chunks	批量保存 Chunk
POST /internal/rag/candidates	保存候选知识点

目录结构

src/
├── main.ts                   # API 进程入口
├── worker.main.ts            # Worker 进程入口
├── app.module.ts             # 根模块
├── modules/                  # 50+ 业务模块
│   ├── auth/
│   ├── admin-auth/
│   ├── ai/
│   ├── knowledge-base/
│   ├── rag-chat/
│   ├── quiz/
│   ├── membership/
│   ├── files/
│   └── ...
├── common/                   # 公共
│   ├── guards/               # Auth Guards (JWT, Admin, Roles, Internal)
│   ├── decorators/           # @AdminPublic, @AdminRoles, @InternalApiKey
│   ├── filters/              # 异常过滤器
│   ├── interceptors/         # 拦截器 (HTTP 日志等)
│   └── utils/                # 工具函数
├── infrastructure/           # 基础设施层
│   ├── database/             # Prisma Service
│   ├── redis/                # Redis Service
│   ├── queue/                # BullMQ 注册
│   ├── storage/              # 存储 (local/COS)
│   └── outbox/               # Outbox 模式
├── workers/                  # Worker 处理器
├── config/                   # 配置
└── test/                     # 测试

接口文档

• 本地：http://localhost:3000/api-docs（无需认证）
• 生产：https://api.longde.cloud/api-docs（Basic Auth）
• Apifox 导入：https://admin:password@api.longde.cloud/api-docs-json

认证体系

用户端：
  JWT Bearer token (Authorization: Bearer <jwt>)
  Refresh token 存储在 RefreshToken 表

管理员：
  httpOnly Cookie (admin_access_token) — Web Admin
  Authorization: Bearer <jwt> — API 调用（兼容 iOS）
  x-api-key — 自动化

Worker：
  x-internal-api-key header

部署

CI/CD（Gitea Actions）

推送 main → 构建 → 集成测试 → 向后兼容测试 → 部署

rsync dist/ + node_modules/ → /opt/zhixi/backend/
systemctl restart zhixi-api + zhixi-nest-worker

生产服务器

组件	运行方式	位置
NestJS API	systemd (zhixi-api)	/opt/zhixi/backend/
NestJS Worker	systemd (zhixi-nest-worker)	/opt/zhixi/backend/
MySQL 8.0	Docker	/data/mysql/
Redis 7	Docker	/data/redis/
Qdrant	Docker	/data/qdrant/
RAG Worker	systemd (zhixi-worker)	/opt/zhixi/rag-worker/

手动部署

npm run build
rsync -av --delete dist/ node_modules/ prisma/ package.json ubuntu@120.53.227.155:/opt/zhixi/backend/
ssh ubuntu@120.53.227.155 'cd /opt/zhixi/backend && npx prisma generate && sudo systemctl restart zhixi-api zhixi-nest-worker'

常用运维命令

# 服务状态
systemctl status zhixi-api zhixi-nest-worker

# 查看日志
journalctl -u zhixi-api -f
journalctl -u zhixi-nest-worker -f

# 数据库迁移
cd /opt/zhixi/backend && npx prisma migrate deploy

# 健康检查
curl http://127.0.0.1:3000/health