AITeachMe云端部署指南:Docker+Nginx+PostgreSQL自托管完整方案,让团队共享学习平台

原创2026-11-16 11:48:191,823 阅读

AITeachMe云端部署指南:Docker+Nginx+PostgreSQL自托管完整方案,让团队共享学习平台

AITeachMe 是一款资料驱动的 AI 学习系统,可以把课程资料转化为可讲、可问、可测的学习空间。本文带你用 Docker + Nginx + PostgreSQL 三步完成 AITeachMe 云端部署,把原本只能单人本地运行的学习工具,变成团队都能访问的共享学习平台。

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/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,它会依次完成:

  1. 执行 Alembic upgrade head(业务表迁移)
  2. 创建 pgvector 扩展、retrieval_chunk.embedding 向量列与 HNSW 索引
  3. 初始化 LlamaIndex PGVectorStore 相关表
  4. 最终 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 进度刷新均正常

AITeachMe 系统设置页面:界面主题与考试分数显示配置

部署成功后,团队成员打开同一个域名即可共享课程、资料库和学习记录,云端设置变更会实时同步(如上图「设置已同步」)。更多部署细节可查阅:

⚠️ 最后提醒:生产迁移前先 pg_dump 备份数据库;ALLOW_CLOUD_VECTOR_REBUILD 默认保持 false,只有明确要重建向量数据时才临时开启。

登录后查看全文
AITeachMe