chore: wire real host-based gitea deploy

2026-06-15 19:58:11 +08:00
parent acfa82b995
commit f69e649c7f
3 changed files with 138 additions and 241 deletions
@@ -2,137 +2,102 @@

 ## Gitea Actions

-本项目使用 Gitea Actions 实现 CI/CD 流水线。
+本项目使用 Gitea Actions + 本机 act_runner 实现 CI/CD。

 ### 工作流文件

 **1. `.gitea/workflows/tests.yml` - 自动化测试**

 触发条件：
- 每次 push 到 main 分支
+- 每次 push 到 `main`
 - 每次创建 Pull Request

 包含任务：
 - `test` - 运行集成测试，生成覆盖率报告
- `lint` - 代码质量检查（Black、Flake8、MyPy）
+- `lint` - 运行 Black / Flake8 / MyPy

 **2. `.gitea/workflows/deploy.yml` - 自动化部署**

 触发条件：
- push 到 main 分支 → 部署到 staging 环境
- 创建 tag (v*) → 部署到 production 环境
+- push 到 `main` → 部署到 staging
+- push tag `v*` → 部署到 production

-当前状态：占位，待补充真实部署脚本
+实际行为：
+- runner 在部署主机本机执行 workflow
+- workflow 将仓库同步到 `/var/lib/xiaoxia-saas-staging/repo` 或 `/var/lib/xiaoxia-saas-production/repo`
+- 读取服务器本地真实 `.env`
+- 本机构建 API / Worker 镜像
+- 使用 `infra/docker/compose.yml` 启动 `postgres` / `redis` / `api` / `worker`
+- 部署后用 `/api/v1/health` 做健康校验
+
+---
+
+## 部署目录约定
+
+### Staging
+- 环境根目录：`/var/lib/xiaoxia-saas-staging`
+- 真实环境文件：`/var/lib/xiaoxia-saas-staging/.env`
+- Actions 同步代码目录：`/var/lib/xiaoxia-saas-staging/repo`
+
+### Production
+- 环境根目录：`/var/lib/xiaoxia-saas-production`
+- 真实环境文件：`/var/lib/xiaoxia-saas-production/.env`
+- Actions 同步代码目录：`/var/lib/xiaoxia-saas-production/repo`

 ---

 ## 本地验证

-在推送前，可以本地运行验证：
+推送前建议先跑：

 ### 运行测试
 ```bash
 pytest tests/integration/ -v --cov=packages --cov=apps --cov-report=html
 ```

-### 代码格式化
+### 代码格式化检查
 ```bash
-black packages/ apps/ tests/
+black --check packages/ apps/ tests/
 ```

-### 代码检查
+### 静态检查
 ```bash
-# Flake8
 flake8 packages/ apps/ tests/ --max-line-length=120 --extend-ignore=E203,W503
-
-# MyPy
 mypy packages/ apps/ --ignore-missing-imports
 ```

-### 排序 imports
-```bash
-isort packages/ apps/ tests/
-```
-
 ---

-## Gitea Actions 配置
+## 当前已验证结论

-### 前提条件
-
-1. Gitea 服务器需要启用 Actions 功能
-2. 需要配置 Actions Runner
-
-### 启用步骤
-
-**在 Gitea 服务器上**：
-
-1. 编辑 `/etc/gitea/app.ini`（或对应配置文件）：
-```ini
-[actions]
-ENABLED = true
-```
-
-2. 重启 Gitea：
-```bash
-systemctl restart gitea
-```
-
-3. 安装 Actions Runner：
-```bash
-# 下载 act_runner
-wget https://dl.gitea.com/act_runner/latest/act_runner-linux-amd64
-chmod +x act_runner-linux-amd64
-mv act_runner-linux-amd64 /usr/local/bin/act_runner
-
-# 注册 runner
-act_runner register --instance http://your-gitea-server --token YOUR_RUNNER_TOKEN
-
-# 运行 runner
-act_runner daemon
-```
-
-4. 在仓库设置中启用 Actions
-
---
-
-## 验证 CI/CD
-
-推送代码后，在 Gitea 仓库页面查看：
- Actions 标签页
- 查看工作流运行状态
- 查看测试结果和覆盖率报告
+- Gitea Actions 已启用
+- `act_runner` 已注册并持续运行
+- staging 可手工部署并已完成真实业务闭环验证
+- 当前 CI/CD 的关键目标是让 Gitea push 后自动完成同机部署，而不是只保留占位 YAML

 ---

 ## 故障排查

-### Actions 未触发
- 检查 Gitea 是否启用 Actions
- 检查工作流文件路径是否正确（`.gitea/workflows/`）
- 检查 YAML 语法是否正确
+### Actions 触发了但 checkout 失败
+优先检查 runner 能否从 job 容器访问 Gitea 实例地址。

-### 测试失败
- 查看 Actions 日志
- 本地运行 `pytest tests/integration/ -v`
- 检查依赖是否完整
+### Deploy 成功但业务链不通
+优先检查：
+- `/var/lib/xiaoxia-saas-staging/.env`
+- `MINIO_ENDPOINT`
+- `DATABASE_URL`
+- worker 日志中的 Celery 任务消费情况

-### Linting 失败
- 本地运行 `black --check packages/`
- 本地运行 `flake8 packages/`
- 修复后重新推送
-
---
-
-## 未来扩展
-
- [ ] 添加性能测试
- [ ] 添加安全扫描
- [ ] 添加 Docker 镜像构建
- [ ] 添加自动化部署脚本
- [ ] 添加 Slack/钉钉通知
+### 健康检查失败
+查看：
+```bash
+docker compose ps
+docker compose logs api --tail=200
+docker compose logs worker --tail=200
+```

 ---

 **最后更新**: 2026-06-15  
-**状态**: 配置完成，待 Gitea Actions 启用
+**状态**: CI/CD 已接入真实主机部署模型，待 push 后持续验证稳定性