环境与首次部署

项目使用 Docker Compose 部署 API、Web 与 Redis。生产环境连接服务器内网 PostgreSQL，测试环境由 Compose 提供 PostgreSQL。服务端容器启动时先运行数据库迁移，再启动 API。实际配置以仓库的 deploy/、docker/ 目录为准。

准备文件

服务器只需要对应环境的 Compose 文件、环境变量文件与 deploy.sh；无需克隆源码或安装 pnpm/Node.js。先在本地查看 deploy/docker-compose.prod.yml、deploy/docker-compose.test.yml 和各环境的 .env.*.docker 模板，再把所需文件放在服务器同一目录。

环境	Compose 文件	数据库
生产	docker-compose.prod.yml	通过 DATABASE_URL 指向已有内网 PostgreSQL
测试	docker-compose.test.yml	Compose 自带 PostgreSQL 容器

首次部署前，按模板生成服务器上的 .env，填写 DATABASE_URL、JWT_SECRET、REDIS_URL 等实际配置。不要把真实密钥提交到仓库。连接串中的密码若含 @ : / ? # 等字符，需进行 URL 编码。

生产环境

生产 Compose 不创建数据库。确认目标 PostgreSQL 已存在目标库，再在部署目录执行：

cp .env.prod.docker .env
# 编辑 .env，填写数据库、密钥与需要覆盖的端口
docker compose -f docker-compose.prod.yml config
docker compose -f docker-compose.prod.yml up -d --pull always
docker compose -f docker-compose.prod.yml ps

config 用于在启动前检查变量展开结果；不要将其中可能包含的密钥输出分享到聊天或工单。服务名为 api、web、redis。

测试环境

cp .env.test.docker .env
# 编辑 .env 后启动
docker compose -f docker-compose.test.yml config
docker compose -f docker-compose.test.yml up -d --pull always
docker compose -f docker-compose.test.yml ps

两个环境的 Compose 项目名不同，可在同一服务器上运行。切换环境时要同步切换对应的 .env，避免连接到错误的数据库或 Redis。

部署后的检查

docker compose -f docker-compose.prod.yml ps
docker compose -f docker-compose.prod.yml logs --tail=100 api
docker compose -f docker-compose.prod.yml logs --tail=100 web

生产环境的 API 应显示 healthy，Web 应处于运行状态。若 API 不健康，先查 API 日志中的数据库迁移或 Redis 连接错误，再查看故障排查。