3.8 KiB
3.8 KiB
AI 知识库系统 V2 部署手册
适用范围
本文档用于 V2 当前版本的部署交接。当前版本包含：
- 后端：FastAPI
- 用户端 H5：Vue 3
- 管理后台：Vue 3 + Element Plus
- 数据库：MySQL 8.x
部署前检查
- 确认服务器已经安装 Docker 和 Docker Compose。
- 确认 MySQL 数据目录有持久化卷或外部数据库。
- 确认以下密钥不再使用开发默认值：
JWT_SECRET_KEYBOOTSTRAP_ADMIN_PASSWORD- 模型 API Key
- 飞书检索服务凭证或适配服务密钥
- 确认防火墙只开放必要端口。
- 确认已经执行数据库备份。
本地开发启动
cd ai_knowledge_base_v2
docker compose -f docker-compose.dev.yml up --build
如果用户端问答需要直读飞书知识库，优先在管理后台“系统设置 / 外部服务”中配置飞书 AppID 和 AppSecret，保存后即可生效，不需要重建容器。
也可以在启动前通过后端运行环境变量配置，作为系统设置为空时的兜底：
export FEISHU_APP_ID=你的飞书应用AppID
export FEISHU_APP_SECRET=你的飞书应用AppSecret
docker compose -f docker-compose.dev.yml up -d --build backend user-client admin-web
也可以在 ai_knowledge_base_v2/.env 中配置 FEISHU_APP_ID、FEISHU_APP_SECRET 和 FEISHU_SEARCH_URL。后台“知识库管理”只维护 SpaceID、NodeID 和启用状态；飞书应用凭证在后台“系统设置”维护，不存放在知识库记录中。若使用独立飞书检索适配服务，则在后台“系统配置”填写飞书检索服务地址，后端会优先调用该地址。
默认地址：
- 统一入口：
http://127.0.0.1:8080/ - 用户端 H5：
http://127.0.0.1:8080/ - 管理后台：
http://127.0.0.1:8080/login - 后端健康检查：
http://127.0.0.1:8080/api/health - 用户端直连调试：
http://127.0.0.1:5173/ - 管理后台直连调试：
http://127.0.0.1:5174/login/ - 后端直连调试：
http://127.0.0.1:8100/api/health - MySQL：
127.0.0.1:3307
单域名访问
当前编排新增 gateway 服务作为统一入口。内网穿透时建议只穿透 gateway:80，域名路径分流如下：
https://qa.huiyushuyuan.cn/ 用户端 H5
https://qa.huiyushuyuan.cn/login 管理后台登录页
https://qa.huiyushuyuan.cn/api/... 后端 API
.env 中推荐配置：
FRP_PROXY_NAME=qa-web
FRP_LOCAL_IP=gateway
FRP_LOCAL_PORT=80
FRP_CUSTOM_DOMAINS=qa.huiyushuyuan.cn
本地开发初始化账号
用户端：
手机号：任意 11 位手机号
验证码：123456
管理后台本地开发环境可通过环境变量初始化首个管理员，例如：
账号：admin
密码：admin123456
生产环境不允许使用上述开发密码。正式部署前必须在 .env 或服务器环境变量中配置安全的 BOOTSTRAP_ADMIN_USERNAME 和 BOOTSTRAP_ADMIN_PASSWORD，并确认管理后台登录页不会预填账号密码。
数据库迁移
后端容器启动时会执行：
alembic upgrade head
如果需要手工执行：
cd apps/backend
alembic upgrade head
备份
可使用脚本：
cd ai_knowledge_base_v2
BACKUP_DIR=./backups ./scripts/mysql_backup.sh
回滚原则
- 先停止新版本服务。
- 切回上一版镜像或上一版 Git commit。
- 如果数据库迁移不可逆，先从备份恢复。
- 恢复后检查：
/api/health- 用户端登录
- 用户端提问
- 管理后台登录
- 管理后台数据列表
生产待补事项
- 前端生产镜像建议改为 Nginx 静态服务，不使用 Vite dev server。
- 模型 API Key 建议加密保存或使用密钥管理服务。
- 后端需要接入结构化日志采集。
- 需要配置 HTTPS、域名、访问日志和基础监控。