csxj2026/junhong_cmp_fiber

Fork 0

Files

huang 589197e284

构建并部署到测试环境（无 SSH） / build-and-deploy (push) Failing after 0s

Details

添加 Docker 和 CI/CD 配置（无 SSH 方案）

2026-01-19 14:56:40 +08:00

13 KiB

Raw Permalink Blame History

君鸿卡管系统 - 部署指南

本文档提供从零开始部署君鸿卡管系统到测试环境的完整步骤。

架构概览

┌─────────────────────────────────────────────────────────────────┐
│                         部署架构图                               │
└───────────────────────────┬─────────────────────────────────────┘
                            │
        ┌───────────────────▼───────────────────┐
        │      开发者 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 环境

# 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 创建部署目录

# 创建部署目录
mkdir -p /home/qycard001/app/junhong_cmp
cd /home/qycard001/app/junhong_cmp

# 创建必要的子目录
mkdir -p configs logs

1.3 准备配置文件

创建 `.env` 文件（数据库迁移配置）

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`（应用配置）

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 到服务器：

# 在服务器上执行
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 配置说明。

只需要配置 2 个 Secrets（非常简单！）：

Secret 名称	值
`REGISTRY_USERNAME`	`junhong_admin`
`REGISTRY_PASSWORD`	`JunHong@2025!Registry`

配置步骤：

进入 Gitea 仓库 → 设置 → Secrets
添加 REGISTRY_USERNAME，值为 junhong_admin
添加 REGISTRY_PASSWORD，值为 JunHong@2025!Registry
完成！

第三步：首次手动部署

在自动化 CI/CD 生效前，先进行一次手动部署验证环境。

3.1 登录 Docker Registry

# 在服务器上执行
ssh qycard001@47.111.166.169 -p 52022

docker login registry.boss160.cn -u junhong_admin
# 输入密码：JunHong@2025!Registry

3.2 手动构建镜像（可选）

如果 CI/CD 还未运行，可以手动构建：

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 启动服务

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 验证部署

# 测试 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`	❌ 否（仅构建镜像）

触发自动部署

# 在本地提交代码
git add .
git commit -m "测试自动部署"
git push origin main

监控部署进度

在 Gitea 仓库页面点击 Actions 标签
查看最新的工作流运行状态
点击工作流查看详细日志

预期日志输出：

✅ 检出代码
✅ 设置镜像标签: latest
✅ 登录 Docker Registry
✅ 构建 API 镜像
✅ 构建 Worker 镜像
✅ 推送镜像到 Registry
✅ 部署到本地
   - 拉取最新镜像...
   - 执行滚动更新...
   - 等待服务健康检查...
   - 清理旧镜像（保留最近 3 个版本）...
   - 部署完成！
✅ 构建结果通知

运维操作

查看服务日志

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 .

重启服务

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

手动执行数据库迁移

# 进入 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

回滚到旧版本

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

清理磁盘空间

# 清理未使用的镜像
docker image prune -a -f

# 清理未使用的容器
docker container prune -f

# 清理未使用的卷
docker volume prune -f

# 一键清理所有（谨慎使用）
docker system prune -a -f --volumes

常见问题

Q1: 容器启动失败，显示 "unhealthy"

排查步骤：

查看容器日志：docker-compose -f docker-compose.prod.yml logs api
检查配置文件是否正确（数据库连接、Redis 连接）
确认外部依赖（PostgreSQL、Redis）是否可访问
手动测试健康检查：curl http://localhost:8088/health

Q2: 数据库迁移失败

可能原因：

数据库连接信息错误
迁移文件损坏
数据库权限不足

解决方法：

# 检查 .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 工作流失败

常见原因：

Secrets 未配置或错误：检查 Gitea Secrets 是否配置了 REGISTRY_USERNAME 和 REGISTRY_PASSWORD
Registry 认证失败：验证用户名密码是否正确
磁盘空间不足：执行 df -h 检查磁盘空间

排查方法：

在 Gitea Actions 页面查看详细日志
在服务器上手动测试 Registry 登录：docker login registry.boss160.cn -u junhong_admin

Q4: 镜像拉取慢或超时

解决方法：

# 检查 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

解决方法：

# 确认 Act Runner 用户在 docker 组中
docker exec -it docker-runner-01 groups

# 如果缺少 docker 组，重启 Act Runner 容器
docker restart docker-runner-01

安全建议

定期更新：
- 定期更新 Docker 和 Docker Compose
- 及时应用系统安全补丁

防火墙配置：

# 仅开放必要端口
sudo ufw allow 52022/tcp   # SSH
sudo ufw allow 8088/tcp    # API（如果需要外部访问）
sudo ufw enable

日志监控：
- 配置日志轮转，防止磁盘占满
- 定期审查访问日志和错误日志
备份策略：
- 定期备份数据库
- 定期备份配置文件（.env、config.yaml）

下一步

部署完成后：

✅ 配置域名和反向代理（Nginx / Caddy）
✅ 启用 HTTPS（Let's Encrypt）
✅ 配置监控和告警（Prometheus + Grafana）
✅ 设置自动备份脚本

支持

如有问题，请联系运维团队或提交 Issue。

13 KiB Raw Permalink Blame History Unescape Escape

君鸿卡管系统 - 部署指南

架构概览

前置准备

1. 服务器环境要求

2. 外部依赖服务

第一步：服务器初始化

1.1 确认 Docker 环境

1.2 创建部署目录

1.3 准备配置文件

创建 .env 文件（数据库迁移配置）

创建 configs/config.yaml（应用配置）

1.4 复制部署文件

第二步：配置 Gitea Secrets

第三步：首次手动部署

3.1 登录 Docker Registry

3.2 手动构建镜像（可选）

3.3 启动服务

3.4 验证部署

第四步：自动化部署

工作流触发规则

触发自动部署

监控部署进度

运维操作

查看服务日志

重启服务

手动执行数据库迁移

回滚到旧版本

清理磁盘空间

常见问题

Q1: 容器启动失败，显示 "unhealthy"

Q2: 数据库迁移失败

Q3: CI/CD 工作流失败

Q4: 镜像拉取慢或超时

Q5: Act Runner 权限问题

安全建议

下一步

支持

13 KiB

Raw Permalink Blame History

创建 `.env` 文件（数据库迁移配置）

创建 `configs/config.yaml`（应用配置）