team-api/docs/deployment-docker.md

Team-API Docker 部署指南

本文档介绍如何使用 Docker 部署 Team-API。

快速开始

一、准备配置文件

# 1. 进入 Docker 配置目录
cd manifest/docker

# 2. 复制配置模板
cp ../../manifest/config/config.example.yaml ./config.yaml

# 3. 编辑配置文件，修改数据库和 Redis 连接信息
vim config.yaml

注意：本配置不对外开放 PostgreSQL 和 Redis 端口，仅应用服务（18888 端口）对外暴露。如需外部访问数据库，请自行添加端口映射。

二、修改 docker-compose.yaml

编辑 docker-compose.yaml 文件，修改以下配置：

1. 数据库密码（第 23 行）：

   POSTGRES_PASSWORD: team_api_secret  # 修改为强密码
   

2. Redis 密码（第 45 行）：

   command: redis-server --appendonly yes --requirepass redis_secret  # 修改为强密码
   

3. 管理员账号（第 76-77 行，可选）：

   INIT_ADMIN_USERNAME: admin          # 修改为你的管理员用户名
   INIT_ADMIN_PASSWORD: admin123       # 修改为你的管理员密码
   

三、修改 config.yaml

编辑 config.yaml 文件，确保数据库和 Redis 配置与 docker-compose.yaml 一致：

database:
  default:
    type: "pgsql"
    link: "pgsql:team_api:team_api_secret@tcp(postgres:5432)/team_api?sslmode=disable"
                        # ^用户名    ^密码              ^主机名:端口    ^数据库名

redis:
  default:
    address: "redis:6379"  # 注意：主机名是 "redis" 而不是 localhost
    pass: "redis_secret"   # 密码需与 docker-compose.yaml 中设置的一致
    db: 0

四、启动服务

# 构建并启动所有服务
docker compose up -d

# 查看日志
docker compose logs -f app

五、访问应用

启动成功后，可以访问：

• 管理后台: http://localhost:18888/admin
• 租户控制台: http://localhost:18888
• API 文档: http://localhost:18888/api/docs

配置说明

docker-compose.yaml 配置项

配置项	说明	默认值
POSTGRES_PASSWORD	数据库密码	team_api_secret
--requirepass	Redis 密码	redis_secret
INIT_ADMIN_USERNAME	管理员用户名	admin
INIT_ADMIN_PASSWORD	管理员密码	admin123

config.yaml 配置项

数据库配置

database:
  default:
    link: "pgsql:用户名:密码@tcp(主机名:端口)/数据库名?sslmode=disable"

注意：Docker 网络中，主机名使用服务名（postgres、redis），而不是 localhost。

Redis 配置

redis:
  default:
    address: "redis:6379"  # 主机名使用 "redis"
    db: 0

JWT 密钥（重要）

jwt:
  secret: "change-me-to-a-random-secret"  # 生产环境必须修改

服务说明

Docker Compose 包含以下服务：

服务	容器名	端口	说明
postgres	team-api-postgres	5432	PostgreSQL 数据库
redis	team-api-redis	6379	Redis 缓存
app	team-api-app	18888	Team-API 应用

常用命令

# 启动服务
docker compose up -d

# 停止服务
docker compose down

# 查看日志
docker compose logs -f

# 仅查看应用日志
docker compose logs -f app

# 重启服务
docker compose restart app

# 重新构建镜像
docker compose build --no-cache
docker compose up -d

# 查看服务状态
docker compose ps

数据持久化

以下数据通过 Docker 卷持久化：

卷名	用途
postgres_data	数据库数据
redis_data	Redis 数据
app_logs	应用日志

清理数据

# 停止并删除容器、网络
docker compose down

# 删除数据卷（注意：会删除所有数据！）
docker volume rm team-api-postgres_data team-api-redis_data team-api-app_logs

生产环境建议

1. 修改默认密码

务必修改以下密码：

• docker-compose.yaml 中的 POSTGRES_PASSWORD
• docker-compose.yaml 中的 INIT_ADMIN_PASSWORD
• config.yaml 中的 jwt.secret

2. 使用外部数据库

对于生产环境，建议使用托管数据库服务。修改 config.yaml 中的数据库连接信息即可。

3. 配置 HTTPS

使用反向代理（如 Nginx）配置 HTTPS：

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:18888;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # WebSocket 支持
    location /api/admin/ws {
        proxy_pass http://localhost:18888;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

故障排查

应用无法启动

1. 检查日志：docker compose logs app
2. 确认 config.yaml 已创建且配置正确
3. 确认数据库和 Redis 就绪：docker compose ps

数据库连接失败

1. 确认 config.yaml 中的密码与 docker-compose.yaml 中的 POSTGRES_PASSWORD 一致
2. 确认主机名使用的是 postgres 而非 localhost
3. 查看数据库日志：docker compose logs postgres

无法访问应用

1. 确认端口未被占用：lsof -i :18888
2. 检查防火墙设置
3. 验证容器状态：docker compose ps

更新应用

# 拉取最新代码
cd ../../
git pull

# 重新构建并启动
cd manifest/docker
docker compose build
docker compose up -d

使用 Make 快捷命令

# 构建镜像
make docker-build

# 启动服务
make docker-up

# 停止服务
make docker-down

# 查看日志
make docker-logs

# 重新构建
make docker-rebuild

# 清理数据
make docker-clean