Docker 部署开源 AI 项目前，先准备这张检查表

很多开源 AI 项目 README 里一句 docker compose up -d，看起来很简单。但真正部署到服务器，问题会集中出现在环境变量、端口、数据库、存储、日志和安全上。

1. 先看 docker-compose.yml

重点看这些字段：

字段	说明
image/build	用现成镜像还是本地构建
ports	暴露哪些端口
environment	需要哪些环境变量
volumes	数据保存在哪里
depends_on	依赖数据库或其他服务
restart	服务挂了是否自动重启

如果没有 volumes，数据可能随容器删除而丢失。

2. 环境变量表

部署前把 .env.example 整理成表：

变量	是否必须	示例	风险
API_KEY	是	sk-xxx	泄露会产生费用
DATABASE_URL	是	postgres://	填错无法启动
AUTH_SECRET	是	随机字符串	太简单有安全风险
PUBLIC_URL	视情况	https://	影响回调和链接

不要把真实 .env 发到公开群或提交到 Git。

3. 端口检查

服务器常见端口冲突：80、443、3000、5432、6379。

检查命令：

lsof -i :3000
lsof -i :80

如果端口被占用，改 compose 里的映射，比如：

ports:
  - "3001:3000"

左边是服务器端口，右边是容器端口。

4. 数据库和存储

如果项目包含数据库，先确认：

• 数据库数据是否挂载到 volume。
• 是否需要初始化迁移。
• 是否有默认账号密码。
• 是否需要备份。

备份不是上线后再想。至少知道数据在哪里。

5. 启动后检查

docker compose ps
docker compose logs -f

检查：

状态	含义
Up	容器已运行
Restarting	启动失败循环
Exited	已退出，需看日志
unhealthy	健康检查失败

不要只看容器 Up，还要访问页面和跑核心功能。

6. 最小验收

检查项	标准
页面可访问	域名或 IP 能打开
登录可用	账号注册或登录正常
API Key 可用	能完成一次模型调用
数据保存	重启后数据不丢
上传文件	如有上传功能，能正常保存
日志可查	报错能定位

7. 安全边界

新手部署最容易忽略：

• 不要暴露数据库端口到公网。
• 默认密码必须改。
• API Key 不要写进前端公开变量。
• 管理后台要有强密码。
• 不确定的项目不要放真实客户数据。

8. 出问题时怎么问 AI

我在用 Docker 部署一个开源 AI 项目。
下面是 docker-compose.yml、.env.example、我实际填写的变量名、执行命令和完整日志。
请按“可能原因 / 验证命令 / 修复方式 / 风险”给排查步骤。
不要让我直接重装服务器。

Docker 部署的关键不是记命令，而是知道服务、端口、变量、数据和日志分别在哪里。