271 lines
5.9 KiB
Markdown
271 lines
5.9 KiB
Markdown
# Team-API Docker 部署指南
|
||
|
||
本文档介绍如何使用 Docker 部署 Team-API。
|
||
|
||
## 快速开始
|
||
|
||
### 一、准备配置文件
|
||
|
||
```bash
|
||
# 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 行）：
|
||
```yaml
|
||
POSTGRES_PASSWORD: team_api_secret # 修改为强密码
|
||
```
|
||
|
||
2. **Redis 密码**（第 45 行）：
|
||
```yaml
|
||
command: redis-server --appendonly yes --requirepass redis_secret # 修改为强密码
|
||
```
|
||
|
||
3. **管理员账号**（第 76-77 行，可选）：
|
||
```yaml
|
||
INIT_ADMIN_USERNAME: admin # 修改为你的管理员用户名
|
||
INIT_ADMIN_PASSWORD: admin123 # 修改为你的管理员密码
|
||
```
|
||
|
||
### 三、修改 config.yaml
|
||
|
||
编辑 `config.yaml` 文件，确保数据库和 Redis 配置与 docker-compose.yaml 一致：
|
||
|
||
```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
|
||
```
|
||
|
||
### 四、启动服务
|
||
|
||
```bash
|
||
# 构建并启动所有服务
|
||
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 配置项
|
||
|
||
#### 数据库配置
|
||
|
||
```yaml
|
||
database:
|
||
default:
|
||
link: "pgsql:用户名:密码@tcp(主机名:端口)/数据库名?sslmode=disable"
|
||
```
|
||
|
||
**注意**：Docker 网络中，主机名使用服务名（`postgres`、`redis`），而不是 `localhost`。
|
||
|
||
#### Redis 配置
|
||
|
||
```yaml
|
||
redis:
|
||
default:
|
||
address: "redis:6379" # 主机名使用 "redis"
|
||
db: 0
|
||
```
|
||
|
||
#### JWT 密钥（重要）
|
||
|
||
```yaml
|
||
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 应用 |
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
# 启动服务
|
||
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` | 应用日志 |
|
||
|
||
## 清理数据
|
||
|
||
```bash
|
||
# 停止并删除容器、网络
|
||
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：
|
||
|
||
```nginx
|
||
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`
|
||
|
||
## 更新应用
|
||
|
||
```bash
|
||
# 拉取最新代码
|
||
cd ../../
|
||
git pull
|
||
|
||
# 重新构建并启动
|
||
cd manifest/docker
|
||
docker compose build
|
||
docker compose up -d
|
||
```
|
||
|
||
## 使用 Make 快捷命令
|
||
|
||
```bash
|
||
# 构建镜像
|
||
make docker-build
|
||
|
||
# 启动服务
|
||
make docker-up
|
||
|
||
# 停止服务
|
||
make docker-down
|
||
|
||
# 查看日志
|
||
make docker-logs
|
||
|
||
# 重新构建
|
||
make docker-rebuild
|
||
|
||
# 清理数据
|
||
make docker-clean
|
||
```
|