固定 Alpine 版本为 3.19 以解决包兼容性问题

.dockerignore

@@ -0,0 +1,61 @@
+# Git 相关
+.git
+.gitignore
+.gitea
+
+# 文档和规范
+README.md
+AGENTS.md
+CLAUDE.md
+docs/
+specs/
+openspec/
+*.md
+
+# 构建产物
+bin/
+api
+worker
+main
+*.exe
+*.dll
+*.so
+*.dylib
+
+# 测试和覆盖率
+tests/
+*_test.go
+*.test
+*.out
+coverage*.out
+
+# 日志文件
+logs/
+*.log
+
+# 临时文件
+tmp/
+temp/
+*.tmp
+*.swp
+*.swo
+*~
+
+# IDE 配置
+.vscode/
+.idea/
+.claude/
+.sisyphus/
+*.iml
+
+# 环境配置（不打包，使用挂载）
+.env
+.env.*
+
+# 其他
+scripts/
+Makefile
+openapi.yaml
+opencode.json
+ai-gateway.conf
+.emdash.json

.gitea/workflows/deploy.yaml

@@ -0,0 +1,92 @@
+name: 构建并部署到测试环境（无 SSH）
+
+on:
+  push:
+    branches:
+      - main
+      - dev
+      - test
+
+env:
+  REGISTRY: registry.boss160.cn
+  API_IMAGE: registry.boss160.cn/junhong/cmp-fiber-api
+  WORKER_IMAGE: registry.boss160.cn/junhong/cmp-fiber-worker
+  DEPLOY_DIR: /home/qycard001/app/junhong_cmp
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: 检出代码
+        run: |
+          git clone https://git.boss160.cn/csxj2026/junhong_cmp_fiber.git .
+          git checkout ${{ github.sha }}
+
+      - name: 设置镜像标签
+        id: tag
+        run: |
+          if [ "${{ github.ref }}" = "refs/heads/main" ]; then
+            echo "tag=latest" >> $GITHUB_OUTPUT
+          elif [ "${{ github.ref }}" = "refs/heads/dev" ]; then
+            echo "tag=dev" >> $GITHUB_OUTPUT
+          elif [ "${{ github.ref }}" = "refs/heads/test" ]; then
+            echo "tag=test" >> $GITHUB_OUTPUT
+          else
+            echo "tag=unknown" >> $GITHUB_OUTPUT
+          fi
+
+      - name: 登录 Docker Registry
+        run: |
+          echo "${{ secrets.REGISTRY_PASSWORD }}" | docker login "${{ env.REGISTRY }}" --username "${{ secrets.REGISTRY_USERNAME }}" --password-stdin
+
+      - name: 构建 API 镜像
+        run: |
+          docker build -f Dockerfile.api -t ${{ env.API_IMAGE }}:${{ steps.tag.outputs.tag }} .
+          docker tag ${{ env.API_IMAGE }}:${{ steps.tag.outputs.tag }} ${{ env.API_IMAGE }}:${{ github.sha }}
+
+      - name: 构建 Worker 镜像
+        run: |
+          docker build -f Dockerfile.worker -t ${{ env.WORKER_IMAGE }}:${{ steps.tag.outputs.tag }} .
+          docker tag ${{ env.WORKER_IMAGE }}:${{ steps.tag.outputs.tag }} ${{ env.WORKER_IMAGE }}:${{ github.sha }}
+
+      - name: 推送镜像到 Registry
+        run: |
+          docker push ${{ env.API_IMAGE }}:${{ steps.tag.outputs.tag }}
+          docker push ${{ env.API_IMAGE }}:${{ github.sha }}
+          docker push ${{ env.WORKER_IMAGE }}:${{ steps.tag.outputs.tag }}
+          docker push ${{ env.WORKER_IMAGE }}:${{ github.sha }}
+
+      - name: 部署到本地（仅 main 分支）
+        if: github.ref == 'refs/heads/main'
+        run: |
+          cd ${{ env.DEPLOY_DIR }}
+          
+          echo "拉取最新镜像..."
+          docker compose -f docker-compose.prod.yml pull
+          
+          echo "执行滚动更新..."
+          docker compose -f docker-compose.prod.yml up -d --no-deps
+          
+          echo "等待服务健康检查..."
+          sleep 10
+          
+          echo "清理旧镜像（保留最近 3 个版本）..."
+          docker images ${{ env.API_IMAGE }} --format "{{.ID}}" | tail -n +4 | xargs -r docker rmi -f || true
+          docker images ${{ env.WORKER_IMAGE }} --format "{{.ID}}" | tail -n +4 | xargs -r docker rmi -f || true
+          
+          echo "清理悬空镜像..."
+          docker image prune -f
+          
+          echo "部署完成！"
+          docker compose -f docker-compose.prod.yml ps
+
+      - name: 构建结果通知
+        if: always()
+        run: |
+          if [ "${{ job.status }}" = "success" ]; then
+            echo "✅ 构建成功: ${{ steps.tag.outputs.tag }}"
+            echo "📦 镜像标签: ${{ github.sha }}"
+          else
+            echo "❌ 构建失败"
+          fi

.gitignore

@@ -72,3 +72,4 @@ cmd/api/api
 api
 .gitignore
 worker
+ai-gateway.conf

Dockerfile.api

@@ -0,0 +1,73 @@
+# ================================
+# 阶段 1: 构建阶段
+# ================================
+FROM golang:1.25.6-alpine AS builder
+
+# 设置工作目录
+WORKDIR /build
+
+# 安装必要的构建工具
+RUN apk add --no-cache git ca-certificates tzdata
+
+# 复制 go.mod 和 go.sum（利用 Docker 缓存）
+COPY go.mod go.sum ./
+
+# 使用国内 Go 代理加速依赖下载
+ENV GOPROXY=https://goproxy.cn,direct
+
+RUN go mod download
+
+# 复制源代码
+COPY . .
+
+# 编译 API 服务（静态链接）
+RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build \
+    -ldflags="-w -s" \
+    -o /build/api \
+    ./cmd/api
+
+# 下载 golang-migrate 工具
+RUN go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest
+
+# ================================
+# 阶段 2: 运行阶段
+# ================================
+FROM alpine:3.19
+
+# 安装运行时依赖
+RUN apk add --no-cache ca-certificates tzdata bash curl
+
+# 设置时区
+ENV TZ=Asia/Shanghai
+
+# 创建非 root 用户
+RUN addgroup -g 1000 appuser && \
+    adduser -D -u 1000 -G appuser appuser
+
+# 设置工作目录
+WORKDIR /app
+
+# 从构建阶段复制二进制文件
+COPY --from=builder /build/api /app/api
+COPY --from=builder /go/bin/migrate /usr/local/bin/migrate
+
+# 复制配置文件和迁移文件
+COPY configs /app/configs
+COPY migrations /app/migrations
+
+# 复制启动脚本
+COPY docker/entrypoint-api.sh /app/entrypoint.sh
+RUN chmod +x /app/entrypoint.sh
+
+# 切换到非 root 用户
+USER appuser
+
+# 暴露端口
+EXPOSE 8088
+
+# 健康检查
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
+    CMD curl -f http://localhost:8088/health || exit 1
+
+# 启动命令
+ENTRYPOINT ["/app/entrypoint.sh"]

Dockerfile.worker

@@ -0,0 +1,57 @@
+# ================================
+# 阶段 1: 构建阶段
+# ================================
+FROM golang:1.25.6-alpine AS builder
+
+# 设置工作目录
+WORKDIR /build
+
+# 安装必要的构建工具
+RUN apk add --no-cache git ca-certificates tzdata
+
+# 复制 go.mod 和 go.sum（利用 Docker 缓存）
+COPY go.mod go.sum ./
+
+# 使用国内 Go 代理加速依赖下载
+ENV GOPROXY=https://goproxy.cn,direct
+
+RUN go mod download
+
+# 复制源代码
+COPY . .
+
+# 编译 Worker 服务（静态链接）
+RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build \
+    -ldflags="-w -s" \
+    -o /build/worker \
+    ./cmd/worker
+
+# ================================
+# 阶段 2: 运行阶段
+# ================================
+FROM alpine:3.19
+
+# 安装运行时依赖
+RUN apk add --no-cache ca-certificates tzdata bash
+
+# 设置时区
+ENV TZ=Asia/Shanghai
+
+# 创建非 root 用户
+RUN addgroup -g 1000 appuser && \
+    adduser -D -u 1000 -G appuser appuser
+
+# 设置工作目录
+WORKDIR /app
+
+# 从构建阶段复制二进制文件
+COPY --from=builder /build/worker /app/worker
+
+# 复制配置文件
+COPY configs /app/configs
+
+# 切换到非 root 用户
+USER appuser
+
+# 启动命令
+CMD ["/app/worker"]

configs/config.yaml

@@ -37,56 +37,29 @@ queue:
   timeout: "10m"
 
 logging:
-  level: "info"
-  development: false
+  level: "debug" # 开发环境使用 debug 级别
+  development: true # 启用开发模式（美化日志输出）
   app_log:
     filename: "logs/app.log"
-    max_size: 100 # MB
-    max_backups: 30
-    max_age: 30 # 天
-    compress: true
+    max_size: 100
+    max_backups: 10 # 开发环境保留较少备份
+    max_age: 7 # 7天
+    compress: false # 开发环境不压缩
   access_log:
     filename: "logs/access.log"
-    max_size: 500 # MB
-    max_backups: 90
-    max_age: 90 # 天
-    compress: true
+    max_size: 100
+    max_backups: 10
+    max_age: 7
+    compress: false
 
 middleware:
-  # 认证中间件开关
-  enable_auth: true
-
-  # 限流中间件开关（默认禁用，按需启用）
-  enable_rate_limiter: false
-
-  # 限流器配置
+  enable_auth: true # 开发环境可选禁用认证
+  enable_rate_limiter: true
   rate_limiter:
-    # 每个时间窗口允许的最大请求数
-    # 建议值：
-    #   - 公开 API（严格）: 60-100
-    #   - 公开 API（宽松）: 1000-5000
-    #   - 内部 API: 5000-10000
-    max: 100
-
-    # 时间窗口（限流重置周期）
-    # 支持格式：
-    #   - "30s" (30秒)
-    #   - "1m"  (1分钟，推荐)
-    #   - "5m"  (5分钟)
-    #   - "1h"  (1小时)
+    max: 1000
     expiration: "1m"
+    storage: "redis"
 
-    # 限流存储方式
-    # 选项：
-    #   - "memory": 内存存储（单机部署，快速，重启后重置）
-    #   - "redis":  Redis存储（分布式部署，持久化，跨服务器共享）
-    # 建议：
-    #   - 开发/测试环境：使用 "memory"
-    #   - 生产环境（单机）：使用 "memory"
-    #   - 生产环境（多机）：使用 "redis"
-    storage: "memory"
-
-# 短信服务配置
 sms:
   gateway_url: "https://gateway.sms.whjhft.com:8443/sms"
   username: "JH0001" # TODO: 替换为实际的短信服务账号
@@ -96,7 +69,7 @@ sms:
 
 # JWT 配置
 jwt:
-  secret_key: "your-secret-key-change-this-in-production" # TODO: 生产环境必须修改
+  secret_key: "dev-secret-key-for-testing-only-32chars!"
   token_duration: "168h" # C 端个人客户 JWT Token 有效期（7天）
   access_token_ttl: "24h" # B 端访问令牌有效期（24小时）
   refresh_token_ttl: "168h" # B 端刷新令牌有效期（7天）

docker-compose.prod.yml

@@ -0,0 +1,58 @@
+version: '3.8'
+
+services:
+  api:
+    image: registry.boss160.cn/junhong/cmp-fiber-api:latest
+    container_name: junhong-cmp-api
+    restart: unless-stopped
+    ports:
+      - "8088:8088"
+    environment:
+      - CONFIG_ENV=prod
+      - DB_HOST=${DB_HOST}
+      - DB_PORT=${DB_PORT}
+      - DB_USER=${DB_USER}
+      - DB_PASSWORD=${DB_PASSWORD}
+      - DB_NAME=${DB_NAME}
+      - DB_SSLMODE=${DB_SSLMODE}
+    volumes:
+      - ./configs:/app/configs:ro
+      - ./logs:/app/logs
+      - ./.env:/app/.env:ro
+    networks:
+      - junhong-network
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8088/health"]
+      interval: 30s
+      timeout: 3s
+      retries: 3
+      start_period: 10s
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10m"
+        max-file: "3"
+
+  worker:
+    image: registry.boss160.cn/junhong/cmp-fiber-worker:latest
+    container_name: junhong-cmp-worker
+    restart: unless-stopped
+    environment:
+      - CONFIG_ENV=prod
+    volumes:
+      - ./configs:/app/configs:ro
+      - ./logs:/app/logs
+    networks:
+      - junhong-network
+    depends_on:
+      api:
+        condition: service_healthy
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10m"
+        max-file: "3"
+
+networks:
+  junhong-network:
+    driver: bridge

docker/entrypoint-api.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+set -e
+
+echo "========================================="
+echo "君鸿卡管系统 API 服务启动中..."
+echo "========================================="
+
+# 检查必要的环境变量
+if [ -z "$DB_HOST" ]; then
+    echo "错误: DB_HOST 环境变量未设置"
+    exit 1
+fi
+
+# 构建数据库连接 URL
+DB_URL="postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_NAME}?sslmode=${DB_SSLMODE}"
+
+echo "检查数据库连接..."
+# 等待数据库就绪（最多等待 30 秒）
+for i in {1..30}; do
+    if migrate -path /app/migrations -database "$DB_URL" version > /dev/null 2>&1; then
+        echo "数据库连接成功"
+        break
+    fi
+    echo "等待数据库就绪... ($i/30)"
+    sleep 1
+done
+
+# 执行数据库迁移
+echo "执行数据库迁移..."
+if migrate -path /app/migrations -database "$DB_URL" up; then
+    echo "数据库迁移完成"
+else
+    echo "警告: 数据库迁移失败或无新迁移"
+fi
+
+# 启动 API 服务
+echo "启动 API 服务..."
+echo "========================================="
+exec /app/api

docs/deployment/deployment-guide.md

@@ -0,0 +1,500 @@
+# 君鸿卡管系统 - 部署指南
+
+本文档提供从零开始部署君鸿卡管系统到测试环境的完整步骤。
+
+---
+
+## 架构概览
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         部署架构图                               │
+└───────────────────────────┬─────────────────────────────────────┘
+                            │
+        ┌───────────────────▼───────────────────┐
+        │      开发者 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。

docs/deployment/gitea-secrets-setup.md

@@ -0,0 +1,114 @@
+# Gitea Secrets 配置说明
+
+本文档说明如何在 Gitea 中配置 CI/CD 工作流所需的 Secrets（密钥）。
+
+## 重要说明
+
+因为 Act Runner 运行在部署服务器本地，所以**不需要 SSH 连接**，配置非常简单！
+
+---
+
+## 配置步骤
+
+### 1. 进入仓库设置
+
+1. 打开你的 Gitea 仓库页面
+2. 点击右上角的 **设置（Settings）** 按钮
+3. 在左侧菜单中找到 **Secrets** 或 **密钥** 选项
+
+### 2. 添加以下 Secrets
+
+点击 **添加 Secret** 按钮，逐个添加以下密钥：
+
+#### Docker Registry 认证信息
+
+| Secret 名称 | 值 | 说明 |
+|------------|-----|------|
+| `REGISTRY_USERNAME` | `junhong_admin` | Docker Registry 用户名 |
+| `REGISTRY_PASSWORD` | `JunHong@2025!Registry` | Docker Registry 密码 |
+
+**就这么简单！只需要 2 个 Secrets！** ✅
+
+---
+
+## 配置完成检查清单
+
+- [ ] `REGISTRY_USERNAME` 已配置
+- [ ] `REGISTRY_PASSWORD` 已配置
+
+---
+
+## 验证配置
+
+### 测试 Registry 登录
+
+在部署服务器上手动测试 Registry 连接：
+
+```bash
+# 登录测试
+docker login registry.boss160.cn -u junhong_admin
+# 输入密码：JunHong@2025!Registry
+
+# 预期输出：Login Succeeded
+```
+
+如果登录成功，说明配置正确。
+
+---
+
+## 常见问题
+
+### Q1: 工作流显示 "secret not found"
+
+**原因**：Secret 名称拼写错误或未添加
+
+**解决方法**：
+1. 检查 Secret 名称是否完全一致（区分大小写）
+2. 确认 2 个 Secrets 都已添加
+
+### Q2: Registry 登录失败
+
+**原因**：用户名或密码错误
+
+**解决方法**：
+```bash
+# 在服务器上手动测试登录
+docker login registry.boss160.cn -u junhong_admin
+# 输入密码：JunHong@2025!Registry
+
+# 如果失败，检查 Registry 认证配置
+cat /home/qycard001/registry/auth/htpasswd
+```
+
+### Q3: 为什么不需要 SSH 密钥？
+
+**回答**：因为你的 Act Runner (`docker-runner-01`) 运行在部署服务器本地，可以直接执行 `docker-compose` 命令，不需要通过 SSH 连接到其他机器。
+
+**架构示意**：
+```
+┌──────────────────────────────────────────┐
+│  部署服务器 (47.111.166.169)             │
+│                                          │
+│  ┌────────────────┐   ┌───────────────┐ │
+│  │ Act Runner     │──→│ Docker Daemon │ │
+│  │(docker-runner) │   │               │ │
+│  └────────────────┘   └───────────────┘ │
+│         ↓                     ↓          │
+│    执行工作流              部署容器       │
+└──────────────────────────────────────────┘
+```
+
+---
+
+## 安全注意事项
+
+1. **绝不**在代码中硬编码密钥信息
+2. **定期更换** Registry 密码
+3. **监控** Gitea Actions 日志，防止密钥泄露
+4. 如果 Secrets 泄露，**立即**更换密码
+
+---
+
+## 下一步
+
+配置完成后，参考 [部署指南](./deployment-guide.md) 进行首次部署。

go.mod

@@ -1,6 +1,6 @@
 module github.com/break/junhong_cmp_fiber
 
-go 1.25.4
+go 1.25
 
 require (
 	github.com/bytedance/sonic v1.14.2