501 lines
13 KiB
Markdown
501 lines
13 KiB
Markdown
# 君鸿卡管系统 - 部署指南
|
||
|
||
本文档提供从零开始部署君鸿卡管系统到测试环境的完整步骤。
|
||
|
||
---
|
||
|
||
## 架构概览
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 部署架构图 │
|
||
└───────────────────────────┬─────────────────────────────────────┘
|
||
│
|
||
┌───────────────────▼───────────────────┐
|
||
│ 开发者 Push 代码到 Gitea │
|
||
│ (main/dev/test 分支) │
|
||
└───────────────────┬───────────────────┘
|
||
│
|
||
┌───────────────────▼───────────────────┐
|
||
│ 部署服务器 (47.111.166.169) │
|
||
│ │
|
||
│ ┌─────────────────────────────────┐ │
|
||
│ │ Act Runner (docker-runner-01) │ │
|
||
│ │ 自动触发工作流 │ │
|
||
│ └───────────┬─────────────────────┘ │
|
||
│ │ │
|
||
│ ┌───────────▼─────────────────────┐ │
|
||
│ │ 构建 Docker 镜像 │ │
|
||
│ │ - API 镜像 │ │
|
||
│ │ - Worker 镜像 │ │
|
||
│ └───────────┬─────────────────────┘ │
|
||
│ │ │
|
||
│ ┌───────────▼─────────────────────┐ │
|
||
│ │ Push 到私有 Docker Registry │ │
|
||
│ │ registry.boss160.cn │ │
|
||
│ └───────────┬─────────────────────┘ │
|
||
│ │ │
|
||
│ ┌───────────▼─────────────────────┐ │
|
||
│ │ 本地部署（无 SSH） │ │
|
||
│ │ - Pull 镜像 │ │
|
||
│ │ - 滚动更新容器 │ │
|
||
│ │ - 清理旧镜像（保留 3 个） │ │
|
||
│ └───────────┬─────────────────────┘ │
|
||
│ │ │
|
||
│ ┌───────────▼─────────────────────┐ │
|
||
│ │ 服务运行中 │ │
|
||
│ │ - API: 0.0.0.0:8088 │ │
|
||
│ │ - Worker: 后台任务处理 │ │
|
||
│ └──────────────────────────────────┘ │
|
||
└───────────────────────────────────────┘
|
||
```
|
||
|
||
**关键优势**：Act Runner 在部署服务器本地运行，无需 SSH，配置简单！
|
||
|
||
---
|
||
|
||
## 前置准备
|
||
|
||
### 1. 服务器环境要求
|
||
|
||
- **操作系统**：Ubuntu 20.04+ / CentOS 7+
|
||
- **Docker**：20.10+
|
||
- **Docker Compose**：1.29+
|
||
- **内存**：至少 2GB
|
||
- **磁盘**：至少 20GB
|
||
- **Act Runner**：已部署并注册到 Gitea（✅ 你已经有了 docker-runner-01）
|
||
|
||
### 2. 外部依赖服务
|
||
|
||
系统依赖以下外部服务（需提前部署）：
|
||
|
||
- **PostgreSQL 14+**：数据库
|
||
- **Redis 6.0+**：缓存和队列
|
||
|
||
---
|
||
|
||
## 第一步：服务器初始化
|
||
|
||
### 1.1 确认 Docker 环境
|
||
|
||
```bash
|
||
# SSH 到服务器
|
||
ssh qycard001@47.111.166.169 -p 52022
|
||
|
||
# 验证 Docker 和 Docker Compose
|
||
docker --version
|
||
docker-compose --version
|
||
|
||
# 验证 Act Runner 正在运行
|
||
docker ps | grep runner
|
||
# 应该能看到 docker-runner-01
|
||
```
|
||
|
||
### 1.2 创建部署目录
|
||
|
||
```bash
|
||
# 创建部署目录
|
||
mkdir -p /home/qycard001/app/junhong_cmp
|
||
cd /home/qycard001/app/junhong_cmp
|
||
|
||
# 创建必要的子目录
|
||
mkdir -p configs logs
|
||
```
|
||
|
||
### 1.3 准备配置文件
|
||
|
||
#### 创建 `.env` 文件（数据库迁移配置）
|
||
|
||
```bash
|
||
cat > /home/qycard001/app/junhong_cmp/.env << 'EOF'
|
||
MIGRATIONS_DIR=migrations
|
||
DB_HOST=cxd.whcxd.cn
|
||
DB_PORT=16159
|
||
DB_USER=erp_pgsql
|
||
DB_PASSWORD=erp_2025
|
||
DB_NAME=junhong_cmp_test
|
||
DB_SSLMODE=disable
|
||
EOF
|
||
```
|
||
|
||
#### 创建 `configs/config.yaml`（应用配置）
|
||
|
||
```bash
|
||
cat > /home/qycard001/app/junhong_cmp/configs/config.yaml << 'EOF'
|
||
server:
|
||
port: 8088
|
||
read_timeout: 60
|
||
write_timeout: 60
|
||
|
||
database:
|
||
host: cxd.whcxd.cn
|
||
port: 16159
|
||
user: erp_pgsql
|
||
password: erp_2025
|
||
dbname: junhong_cmp_test
|
||
sslmode: disable
|
||
max_open_conns: 100
|
||
max_idle_conns: 10
|
||
|
||
redis:
|
||
host: 你的Redis地址
|
||
port: 6379
|
||
password: ""
|
||
db: 0
|
||
|
||
logging:
|
||
level: info
|
||
output: logs/app.log
|
||
max_size: 100
|
||
max_backups: 7
|
||
max_age: 30
|
||
compress: true
|
||
|
||
middleware:
|
||
enable_auth: true
|
||
enable_rate_limiter: false
|
||
EOF
|
||
```
|
||
|
||
**重要**：将 `你的Redis地址` 替换为实际的 Redis 地址。
|
||
|
||
### 1.4 复制部署文件
|
||
|
||
从代码仓库复制 `docker-compose.prod.yml` 到服务器：
|
||
|
||
```bash
|
||
# 在服务器上执行
|
||
cd /home/qycard001/app/junhong_cmp
|
||
|
||
# 方式1: 使用 Git（推荐）
|
||
git clone <你的仓库地址> temp
|
||
cp temp/docker-compose.prod.yml ./docker-compose.prod.yml
|
||
rm -rf temp
|
||
|
||
# 方式2: 从本地上传
|
||
# 在本地执行：
|
||
# scp -P 52022 docker-compose.prod.yml qycard001@47.111.166.169:/home/qycard001/app/junhong_cmp/
|
||
```
|
||
|
||
---
|
||
|
||
## 第二步：配置 Gitea Secrets
|
||
|
||
详细步骤请参考 [Gitea Secrets 配置说明](./gitea-secrets-setup.md)。
|
||
|
||
**只需要配置 2 个 Secrets**（非常简单！）：
|
||
|
||
| Secret 名称 | 值 |
|
||
|------------|-----|
|
||
| `REGISTRY_USERNAME` | `junhong_admin` |
|
||
| `REGISTRY_PASSWORD` | `JunHong@2025!Registry` |
|
||
|
||
**配置步骤**：
|
||
1. 进入 Gitea 仓库 → 设置 → Secrets
|
||
2. 添加 `REGISTRY_USERNAME`，值为 `junhong_admin`
|
||
3. 添加 `REGISTRY_PASSWORD`，值为 `JunHong@2025!Registry`
|
||
4. 完成！
|
||
|
||
---
|
||
|
||
## 第三步：首次手动部署
|
||
|
||
在自动化 CI/CD 生效前，先进行一次手动部署验证环境。
|
||
|
||
### 3.1 登录 Docker Registry
|
||
|
||
```bash
|
||
# 在服务器上执行
|
||
ssh qycard001@47.111.166.169 -p 52022
|
||
|
||
docker login registry.boss160.cn -u junhong_admin
|
||
# 输入密码：JunHong@2025!Registry
|
||
```
|
||
|
||
### 3.2 手动构建镜像（可选）
|
||
|
||
如果 CI/CD 还未运行，可以手动构建：
|
||
|
||
```bash
|
||
cd <代码仓库目录>
|
||
|
||
# 构建 API 镜像
|
||
docker build -f Dockerfile.api -t registry.boss160.cn/junhong/cmp-fiber-api:latest .
|
||
|
||
# 构建 Worker 镜像
|
||
docker build -f Dockerfile.worker -t registry.boss160.cn/junhong/cmp-fiber-worker:latest .
|
||
|
||
# 推送镜像
|
||
docker push registry.boss160.cn/junhong/cmp-fiber-api:latest
|
||
docker push registry.boss160.cn/junhong/cmp-fiber-worker:latest
|
||
```
|
||
|
||
### 3.3 启动服务
|
||
|
||
```bash
|
||
cd /home/qycard001/app/junhong_cmp
|
||
|
||
# 拉取镜像
|
||
docker-compose -f docker-compose.prod.yml pull
|
||
|
||
# 启动服务
|
||
docker-compose -f docker-compose.prod.yml up -d
|
||
|
||
# 查看服务状态
|
||
docker-compose -f docker-compose.prod.yml ps
|
||
|
||
# 查看日志
|
||
docker-compose -f docker-compose.prod.yml logs -f
|
||
```
|
||
|
||
### 3.4 验证部署
|
||
|
||
```bash
|
||
# 测试 API 健康检查
|
||
curl http://localhost:8088/health
|
||
|
||
# 预期输出：
|
||
# {"code":0,"msg":"ok","data":{"status":"healthy"},"timestamp":1234567890}
|
||
|
||
# 查看容器状态
|
||
docker ps | grep junhong
|
||
```
|
||
|
||
---
|
||
|
||
## 第四步：自动化部署
|
||
|
||
配置完成后，每次 Push 代码到 `main` / `dev` / `test` 分支时，会自动触发构建。
|
||
|
||
### 工作流触发规则
|
||
|
||
| 分支 | 镜像标签 | 是否自动部署 |
|
||
|------|---------|------------|
|
||
| `main` | `latest` | ✅ 是 |
|
||
| `dev` | `dev` | ❌ 否（仅构建镜像）|
|
||
| `test` | `test` | ❌ 否（仅构建镜像）|
|
||
|
||
### 触发自动部署
|
||
|
||
```bash
|
||
# 在本地提交代码
|
||
git add .
|
||
git commit -m "测试自动部署"
|
||
git push origin main
|
||
```
|
||
|
||
### 监控部署进度
|
||
|
||
1. 在 Gitea 仓库页面点击 **Actions** 标签
|
||
2. 查看最新的工作流运行状态
|
||
3. 点击工作流查看详细日志
|
||
|
||
**预期日志输出**：
|
||
```
|
||
✅ 检出代码
|
||
✅ 设置镜像标签: latest
|
||
✅ 登录 Docker Registry
|
||
✅ 构建 API 镜像
|
||
✅ 构建 Worker 镜像
|
||
✅ 推送镜像到 Registry
|
||
✅ 部署到本地
|
||
- 拉取最新镜像...
|
||
- 执行滚动更新...
|
||
- 等待服务健康检查...
|
||
- 清理旧镜像（保留最近 3 个版本）...
|
||
- 部署完成！
|
||
✅ 构建结果通知
|
||
```
|
||
|
||
---
|
||
|
||
## 运维操作
|
||
|
||
### 查看服务日志
|
||
|
||
```bash
|
||
cd /home/qycard001/app/junhong_cmp
|
||
|
||
# 查看 API 日志
|
||
docker-compose -f docker-compose.prod.yml logs -f api
|
||
|
||
# 查看 Worker 日志
|
||
docker-compose -f docker-compose.prod.yml logs -f worker
|
||
|
||
# 查看应用日志文件
|
||
tail -f logs/app.log | jq .
|
||
tail -f logs/access.log | jq .
|
||
```
|
||
|
||
### 重启服务
|
||
|
||
```bash
|
||
cd /home/qycard001/app/junhong_cmp
|
||
|
||
# 重启所有服务
|
||
docker-compose -f docker-compose.prod.yml restart
|
||
|
||
# 重启单个服务
|
||
docker-compose -f docker-compose.prod.yml restart api
|
||
docker-compose -f docker-compose.prod.yml restart worker
|
||
```
|
||
|
||
### 手动执行数据库迁移
|
||
|
||
```bash
|
||
# 进入 API 容器
|
||
docker exec -it junhong-cmp-api bash
|
||
|
||
# 查看当前迁移版本
|
||
migrate -path /app/migrations -database "$(cat /app/.env | grep DB_ | xargs)" version
|
||
|
||
# 执行迁移（通常容器启动时会自动执行）
|
||
migrate -path /app/migrations -database "$(cat /app/.env | grep DB_ | xargs)" up
|
||
```
|
||
|
||
### 回滚到旧版本
|
||
|
||
```bash
|
||
cd /home/qycard001/app/junhong_cmp
|
||
|
||
# 查看可用镜像
|
||
docker images | grep cmp-fiber
|
||
|
||
# 示例输出：
|
||
# registry.boss160.cn/junhong/cmp-fiber-api latest abc123 2 hours ago 50MB
|
||
# registry.boss160.cn/junhong/cmp-fiber-api def456 def456 1 day ago 50MB
|
||
|
||
# 修改 docker-compose.prod.yml 中的镜像标签
|
||
# 将 :latest 改为具体的 commit SHA
|
||
sed -i 's/:latest/:def456/g' docker-compose.prod.yml
|
||
|
||
# 重新部署
|
||
docker-compose -f docker-compose.prod.yml pull
|
||
docker-compose -f docker-compose.prod.yml up -d
|
||
```
|
||
|
||
### 清理磁盘空间
|
||
|
||
```bash
|
||
# 清理未使用的镜像
|
||
docker image prune -a -f
|
||
|
||
# 清理未使用的容器
|
||
docker container prune -f
|
||
|
||
# 清理未使用的卷
|
||
docker volume prune -f
|
||
|
||
# 一键清理所有（谨慎使用）
|
||
docker system prune -a -f --volumes
|
||
```
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### Q1: 容器启动失败，显示 "unhealthy"
|
||
|
||
**排查步骤**：
|
||
1. 查看容器日志：`docker-compose -f docker-compose.prod.yml logs api`
|
||
2. 检查配置文件是否正确（数据库连接、Redis 连接）
|
||
3. 确认外部依赖（PostgreSQL、Redis）是否可访问
|
||
4. 手动测试健康检查：`curl http://localhost:8088/health`
|
||
|
||
### Q2: 数据库迁移失败
|
||
|
||
**可能原因**：
|
||
- 数据库连接信息错误
|
||
- 迁移文件损坏
|
||
- 数据库权限不足
|
||
|
||
**解决方法**：
|
||
```bash
|
||
# 检查 .env 文件配置
|
||
cat /home/qycard001/app/junhong_cmp/.env
|
||
|
||
# 手动测试数据库连接
|
||
docker run --rm postgres:14 psql "postgresql://erp_pgsql:erp_2025@cxd.whcxd.cn:16159/junhong_cmp_test?sslmode=disable" -c "SELECT 1;"
|
||
|
||
# 查看迁移日志
|
||
docker logs junhong-cmp-api | grep migrate
|
||
```
|
||
|
||
### Q3: CI/CD 工作流失败
|
||
|
||
**常见原因**：
|
||
1. **Secrets 未配置或错误**：检查 Gitea Secrets 是否配置了 `REGISTRY_USERNAME` 和 `REGISTRY_PASSWORD`
|
||
2. **Registry 认证失败**：验证用户名密码是否正确
|
||
3. **磁盘空间不足**：执行 `df -h` 检查磁盘空间
|
||
|
||
**排查方法**：
|
||
- 在 Gitea Actions 页面查看详细日志
|
||
- 在服务器上手动测试 Registry 登录：`docker login registry.boss160.cn -u junhong_admin`
|
||
|
||
### Q4: 镜像拉取慢或超时
|
||
|
||
**解决方法**：
|
||
```bash
|
||
# 检查 Registry 连接
|
||
curl -I https://registry.boss160.cn
|
||
|
||
# 检查网络
|
||
ping registry.boss160.cn
|
||
|
||
# 查看 Docker 日志
|
||
journalctl -u docker -f
|
||
```
|
||
|
||
### Q5: Act Runner 权限问题
|
||
|
||
**问题现象**：工作流报错 `permission denied` 或 `cannot connect to Docker daemon`
|
||
|
||
**解决方法**：
|
||
```bash
|
||
# 确认 Act Runner 用户在 docker 组中
|
||
docker exec -it docker-runner-01 groups
|
||
|
||
# 如果缺少 docker 组，重启 Act Runner 容器
|
||
docker restart docker-runner-01
|
||
```
|
||
|
||
---
|
||
|
||
## 安全建议
|
||
|
||
1. **定期更新**：
|
||
- 定期更新 Docker 和 Docker Compose
|
||
- 及时应用系统安全补丁
|
||
|
||
2. **防火墙配置**：
|
||
```bash
|
||
# 仅开放必要端口
|
||
sudo ufw allow 52022/tcp # SSH
|
||
sudo ufw allow 8088/tcp # API（如果需要外部访问）
|
||
sudo ufw enable
|
||
```
|
||
|
||
3. **日志监控**：
|
||
- 配置日志轮转，防止磁盘占满
|
||
- 定期审查访问日志和错误日志
|
||
|
||
4. **备份策略**：
|
||
- 定期备份数据库
|
||
- 定期备份配置文件（`.env`、`config.yaml`）
|
||
|
||
---
|
||
|
||
## 下一步
|
||
|
||
部署完成后：
|
||
1. ✅ 配置域名和反向代理（Nginx / Caddy）
|
||
2. ✅ 启用 HTTPS（Let's Encrypt）
|
||
3. ✅ 配置监控和告警（Prometheus + Grafana）
|
||
4. ✅ 设置自动备份脚本
|
||
|
||
---
|
||
|
||
## 支持
|
||
|
||
如有问题，请联系运维团队或提交 Issue。
|