# CI/CD Configuration

## Gitea Actions

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

### 工作流文件

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

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

包含任务：
- `test` - 运行集成测试，生成覆盖率报告
- `lint` - 运行 Black / Flake8 / MyPy

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

触发条件：
- 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 --check packages/ apps/ tests/
```

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

---

## 当前已验证结论

- Gitea Actions 已启用
- `act_runner` 已注册并持续运行
- staging 可手工部署并已完成真实业务闭环验证
- 当前 CI/CD 的关键目标是让 Gitea push 后自动完成同机部署，而不是只保留占位 YAML

---

## 故障排查

### Actions 触发了但 checkout 失败
优先检查 runner 能否从 job 容器访问 Gitea 实例地址；如果 Gitea 挂在 `/git` 这类子路径下，优先使用手写 `git fetch`，不要依赖 `actions/checkout` 自动拼接仓库地址。

### Deploy 成功但业务链不通
优先检查：
- `/var/lib/xiaoxia-saas-staging/.env`
- `MINIO_ENDPOINT`
- `DATABASE_URL`
- worker 日志中的 Celery 任务消费情况

### 健康检查失败
查看：
```bash
docker compose ps
docker compose logs api --tail=200
docker compose logs worker --tail=200
```

---

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