AITeachMe云端部署指南:Docker+Nginx+PostgreSQL自托管完整方案,让团队共享学习平台
AITeachMe云端部署指南:Docker+Nginx+PostgreSQL自托管完整方案,让团队共享学习平台
AITeachMe 是一款资料驱动的 AI 学习系统,可以把课程资料转化为可讲、可问、可测的学习空间。本文带你用 Docker + Nginx + PostgreSQL 三步完成 AITeachMe 云端部署,把原本只能单人本地运行的学习工具,变成团队都能访问的共享学习平台。
一、为什么选择云端自托管
本地模式(SQLite + 本地存储)适合个人试用,但团队共享场景需要更强的能力:
| 维度 | 本地模式 | 云端模式 |
|---|---|---|
| 数据库 | SQLite | PostgreSQL + pgvector(支持向量检索) |
| 文件存储 | 本地目录 | S3 兼容对象存储(OSS) |
| 鉴权 | 可关闭 | 账号体系,支持 OAuth 登录 |
| 访问方式 | 仅本机 | 公网域名,团队共享 |
云端模式下,所有课程、知识文档、学习画像都沉淀在统一的 PostgreSQL 数据库中,成员之间可以共享课程包(.atmx)和分享链接,这正是「让团队共享学习平台」的核心。架构细节可参考 docs/deployment/cloud-architecture.md。
二、部署架构总览
推荐的生产形态是「前端 Nginx 对外,后端走内网」:
Browser
-> https://<frontend-domain> (前端 Nginx 静态容器)
-> Nginx /api 反向代理
-> <backend:9020> (后端 FastAPI,仅内网)
-> PostgreSQL + pgvector(仅内网)
-> S3-compatible OSS(对象存储)
关键设计:后端不暴露公网地址,外部用户只访问前端域名,Nginx 再把 /api 请求反代到后端内网服务,安全性更好。这个方案的完整说明见 docs/deployment/sealos-frontend.md。
先克隆仓库:
git clone https://gitcode.com/gh_mirrors/ai/AITeachMe
三、一键本地试运行:Docker Compose 快速验证
仓库自带 Compose 编排文件 infra/deployment/compose/docker-compose.yml,包含后端(9020 端口)和前端 Nginx(80 端口)两个服务。在仓库根目录执行:
docker compose -f infra/deployment/compose/docker-compose.yml up --build
构建完成后验证:
- 前端:浏览器访问
http://localhost - 后端:
http://localhost:9020/api/health返回健康即成功
停止服务:
docker compose -f infra/deployment/compose/docker-compose.yml down
提示:这份 Compose 默认是
local单机模式(SQLite + 本地卷),适合先跑通链路;正式云端部署请切换到APP_MODE=cloud+ PostgreSQL + S3 的组合。
四、构建后端镜像:轻量版与 Office 版二选一
仓库提供两份后端镜像定义,按需选择:
- infra/deployment/docker/backend.Dockerfile:轻量镜像,只含 Python 运行依赖,基于
uv管理依赖,非 root 用户运行,默认端口 9020 - infra/deployment/docker/backend-office.Dockerfile:额外预装 LibreOffice/soffice,用于 Office 文档转 PDF 链路,体积更大
前端镜像 infra/deployment/docker/frontend.Dockerfile 采用多阶段构建:Node 构建 React 静态产物和文档站,最终由 nginx:alpine 托管,并通过环境变量 AITEACHME_API_UPSTREAM 在容器启动时动态注入后端地址。
# 示例:构建轻量后端镜像
docker build -f infra/deployment/docker/backend.Dockerfile -t aiteachme-backend:slim .
五、初始化 PostgreSQL:一条命令完成建表与向量配置
云端部署的铁律是禁止应用启动时自动建表/删表,所有 schema 变更统一走 Alembic 迁移(backend/migrations/versions/)。仓库提供了云端数据库的单一入口脚本 backend/scripts/bootstrap_cloud_db.py,它会依次完成:
- 执行 Alembic
upgrade head(业务表迁移) - 创建
pgvector扩展、retrieval_chunk.embedding向量列与 HNSW 索引 - 初始化 LlamaIndex PGVectorStore 相关表
- 最终 schema 检查,通过后才允许切流
APP_MODE=cloud DATABASE_URL=postgresql://<user>:<pass>@<host>:5432/aiteachme \
python backend/scripts/bootstrap_cloud_db.py
后端镜像的默认启动命令 backend/scripts/start_cloud_app.py 是「fail-closed」的:先校验 APP_MODE、PostgreSQL、S3、鉴权配置是否完整,再做数据库 bootstrap,最后才启动 uvicorn——配置不完整时会直接拒绝启动,避免带病上线。
数据库迁移的完整口径见 docs/deployment/cloud-db-migrations.md。
六、Nginx 反向代理:两个必配要点
参考仓库自带的 infra/deployment/nginx/default.conf,生产环境有两个容易踩坑的配置:
1. 上传与 SSE 大请求体限制
资料上传和 .atmx 课程包导入(上限 256MB)走 client_max_body_size 260m。如果外层 Ingress 或网关还有限制,记得同步放大到至少 260m,否则请求会先被网关拦截。
2. 关闭 SSE 响应缓冲
课程构建、考试生成等长任务依赖 Server-Sent Events 实时推送进度,/api 反代必须配置:
proxy_buffering off;
proxy_request_buffering off;
proxy_read_timeout 3600;
gzip off;
漏配 proxy_buffering off 是「页面进度条卡住不动」的头号原因。
七、云端环境变量清单
以下是云端部署的核心环境变量速查表(完整版见 docs/deployment/cloud-deployment.md):
# 运行模式(线上必须显式 cloud)
APP_MODE=cloud
PORT=9020
# 数据库(建议用连接池地址)
DATABASE_URL=postgresql://<pooled-connection-string>
# 对象存储(S3 兼容)
STORAGE_BACKEND=s3
S3_CREDENTIAL_MODE=static
S3_BUCKET=<bucket>
S3_ENDPOINT=<s3-endpoint>
S3_ACCESS_KEY=<access-key>
S3_SECRET_KEY=<secret-key>
S3_REGION=<region>
S3_ADDRESSING_STYLE=virtual
# 鉴权(必须开启)
AUTH_ENABLED=true
AUTH_TOKEN_SECRET=<至少32位随机字符>
AUTH_SESSION_COOKIE_SECURE=true
# 跨域(只列真实前端来源)
CORS_ALLOWED_ORIGINS=https://<frontend-domain>
# 大模型
LLM_API_KEY=<model-api-key>
LLM_BASE_URL=<model-api-base-url>
LLM_CONCURRENCY_LIMIT=8
几个安全要点:
AUTH_TOKEN_SECRET必须是 32 位以上随机字符串,妥善保存——数据库备份的解密依赖它- 会话 Cookie 保持
Secure + HttpOnly - 未配置完整的 OAuth provider(如 Google/QQ/微信三项齐全)不会显示在前端,可先不配
八、上线核对清单 🎯
部署完成后,按这份清单逐项验证:
- [ ] 通过前端域名访问
GET /api/health正常 - [ ] PostgreSQL 已完成
bootstrap_cloud_db.py迁移与检查 - [ ] 对象存储变量完整,可上传/读取测试文件
- [ ]
AUTH_ENABLED=true,注册/登录流程正常 - [ ] 首位管理员通过
python backend/scripts/set_admin_role.py --email <邮箱>提升 - [ ] 前端域名已加入
CORS_ALLOWED_ORIGINS - [ ] 浏览器实测:新建课程、上传资料、知识文档构建、SSE 进度刷新均正常
部署成功后,团队成员打开同一个域名即可共享课程、资料库和学习记录,云端设置变更会实时同步(如上图「设置已同步」)。更多部署细节可查阅:
- 云端部署总览:docs/deployment/cloud-deployment.md
- 云端数据库迁移:docs/deployment/cloud-db-migrations.md
- 前端 Nginx 部署:docs/deployment/sealos-frontend.md
⚠️ 最后提醒:生产迁移前先
pg_dump备份数据库;ALLOW_CLOUD_VECTOR_REBUILD默认保持false,只有明确要重建向量数据时才临时开启。

