# patch-merge-system
**Repository Path**: ecky88/patch-merge-system
## Basic Information
- **Project Name**: patch-merge-system
- **Description**: 这是一个patch-merge-system
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-30
- **Last Updated**: 2026-09-10
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# Patch 合并系统一体化镜像
这是 Patch 合并系统的可运行脚手架。单个 Debian 13（Trixie）镜像包含 Python/FastAPI、Vue.js、PostgreSQL、Codex CLI，以及用于管理非官方模型供应商配置的 CC Switch CLI。
| 组件 | 固定版本 |
|---|---:|
| Debian | 13 / Trixie（基础镜像滚动补丁已固定 digest） |
| Python | 3.14.6 |
| FastAPI | 0.139.2 |
| Uvicorn | 0.51.0 |
| Vue | 3.5.40 |
| Vite | 8.1.5 |
| Node.js | 26.5.0 |
| npm | 12.0.1 |
| PostgreSQL | 18.4 |
| Codex CLI (`@openai/codex`) | 0.145.0 |
| CC Switch CLI | 5.9.3 |
版本于 **2026-07-24** 从官方 PyPI、npm、Docker Hub/PostgreSQL 发布信息和 CC Switch CLI 文档核实。基础镜像同时固定了 tag 和 digest，避免同名 tag 漂移。
## 端口规划
| 模块 | 容器端口 | Compose 默认宿主机绑定 |
|---|---:|---|
| FastAPI 后端 | `5555` | `127.0.0.1:5555` |
| Vue 前端静态服务 | `5556` | `127.0.0.1:5556` |
| PostgreSQL 数据库 | `5557` | `127.0.0.1:5557` |
前端页面从 `5556` 加载，浏览器请求 `5555` 上的后端 API；后端连接容器内 `127.0.0.1:5557` 的 PostgreSQL。CC Switch 是命令行工具，不启动 Web 服务，也不暴露额外端口。
## 为什么这样组织
用户要求 Python FastAPI、Vue.js、PostgreSQL、Codex CLI 四套环境进入一个 image；Codex CLI 配置需要支持非官方模型供应商 key。因此镜像内同时保留上述运行时，并安装 `cc-switch` CLI 用于配置/切换供应商。
生产环境通常更推荐 PostgreSQL 独立容器/托管数据库，本镜像当前更适合作为开发、验证和封闭部署基线。
Codex CLI 和 CC Switch CLI 安装在镜像中；MVP 的 Web API 只在工单演练时检查 `codex --version` 并生成占位报告，**不会**接收任意 Codex prompt 或执行真实合并命令。API Key、登录凭据、供应商密钥也不会写进镜像。
## 构建
```bash
docker build -t patch-merge-system:0.2.0 .
```
网络受限时可以指定包镜像、基础镜像代理或 CC Switch CLI 版本：
```bash
docker build -t patch-merge-system:0.2.0 \
--build-arg PIP_INDEX_URL=https://pypi.org/simple \
--build-arg NPM_REGISTRY=https://registry.npmjs.org \
--build-arg CC_SWITCH_CLI_VERSION=5.9.3 \
--build-arg PYTHON_IMAGE=python:3.14.6-slim-trixie@sha256:cea0e6040540fb2b965b6e7fb5ffa00871e632eef63719f0ea54bca189ce14a6 \
--build-arg NODE_IMAGE=node:26.5.0-trixie-slim@sha256:715e55e4b84e4bb0ff48e49b398a848f08e55daed8eb6a0ea1839ae53bc57583 \
--build-arg POSTGRES_IMAGE=postgres:18.4-trixie@sha256:3a82e1f56c8f0f5616a11103ac3d47e632c3938698946a7ad26da0df1334744a \
.
```
说明：`cc-switch` 使用 `SaladDay/cc-switch-cli` 的 Linux x64 musl release 包安装到 `/usr/local/bin/cc-switch`。它是 CLI/TUI 工具，不是 Web 服务。
## 启动
### 本机 Windows 一键启动
推荐双击或在 cmd 中执行显式 Windows 脚本：
```cmd
start-patch-merge-system-windows.cmd
```
兼容旧入口仍可用：
```cmd
start-patch-merge-system.cmd
```
如需强制重新构建镜像，可执行：
```cmd
powershell -NoProfile -ExecutionPolicy Bypass -File start-patch-merge-system-windows.ps1 -ForceBuild
```
Windows 脚本会自动完成：
1. 检查 Docker Desktop 是否就绪。
2. 如不存在 `.env`，自动生成本地 PostgreSQL 密码。
3. 构建 `patch-merge-system:0.2.0` 镜像；如果 Docker Hub 网络不可达，会自动尝试基于本机已有的 `patch-merge-system:0.1.2` 做离线升级构建。
4. 创建宿主机工作区目录：`D:\Program Files\QwenPaw\data\workspaces\patch-merge-dev-agent\patch-merge-system-workspace`。
5. 创建 Docker 命名卷 `patch-merge-workspace`，并绑定到上述目录，容器内挂载为 `/workspace`。
6. 在 `patch-merge-workspace` 下自动创建运行子目录：`postgres-data`、`codex-home`、`cc-switch-home`、`repo`、`patches`、`reports`、`runs`。
7. 启动服务并自动打开前端后台。
### 远程 Ubuntu 服务器一键启动
远程部署服务器使用：
```bash
chmod +x start-patch-merge-system-ubuntu.sh
./start-patch-merge-system-ubuntu.sh
```
Ubuntu 脚本默认创建/使用宿主机工作区：
```text
/home/gitlab-idata/diskc/services/patch-auto-service/workspace
```
并创建 external Docker 命名卷：
```text
patch-merge-workspace -> /home/gitlab-idata/diskc/services/patch-auto-service/workspace
```
容器内统一挂载为 `/workspace`。所有运行数据仍位于该工作区的子目录下：`postgres-data`、`codex-home`、`cc-switch-home`、`repo`、`patches`、`reports`、`runs`。
Ubuntu 脚本默认把前端和后端绑定到 `0.0.0.0`，便于远程访问；PostgreSQL 默认只绑定到服务器本机 `127.0.0.1:5557`，不对外暴露数据库。若需要指定公网域名/IP 或额外 CORS 来源，可在启动前设置：
```bash
export PATCH_MERGE_PUBLIC_HOST=your.server.domain.or.ip
export PATCH_MERGE_EXTRA_CORS_ORIGINS=http://your.server.domain.or.ip:5556
./start-patch-merge-system-ubuntu.sh
```
离线部署时，可先在有镜像的机器导出：
```bash
docker save patch-merge-system:0.2.0 -o patch-merge-system_0.2.0.tar
```
上传到服务器后加载并启动：
```bash
./start-patch-merge-system-ubuntu.sh --image-tar ./patch-merge-system_0.2.0.tar
```
如需手动启动，先在项目目录创建不提交 Git 的 `.env`，至少写入一条强随机密码：
```dotenv
POSTGRES_PASSWORD=请替换为强随机密码
```
然后确保 `patch-merge-workspace` 命名卷已创建，再启动：
```bash
docker compose up -d --build
```
`.gitignore` 已排除 `.env`。不要把真实密码提交到 Git。
访问：
- 前端页面：
- 后端健康检查：
- 后端组件版本：
- Swagger UI：
- PostgreSQL：`127.0.0.1:5557`
前端管理后台包含：
- 信息概览：展示邮箱监听、需求/工单数量、资源关系、执行流水线和最近运行事件。
- 运行看板：查看当前需求清单、编辑人工确认单、转为 Patch 合并工单、执行 Codex CLI dry-run 演练并生成报告。
- 资源调度：维护产品、基线、Gerrit manifest 入口和可编译服务器关系，例如 `ssh://source.idata.com/project/manifests -b MT8791_V_GMS -m custom/MT8791_V_GMS_AGN.xml`。
- 智能体设置：配置需求确认单生成、合并执行、报告生成三个 Codex CLI 参与环节。
- 信使服务：预置企业微信群、企业微信智能机器人、邮件通知三个通道的配置入口。
- 系统设置：配置 Codex CLI 路径、Token Key（不回显）、Patch 工作区、邮箱监听参数。
后端 API 会在首次启动时自动初始化 PostgreSQL 表结构和默认配置。MVP 阶段的邮箱扫描、Codex 合并执行、通知发送先做成可配置入口和状态流转；真实 IMAP 解析、patch 安全校验、隔离工作区 git apply/commit 会在下一迭代补齐。
本地连接数据库示例：
```bash
psql -h 127.0.0.1 -p 5557 -U patchmerge -d patchmerge
```
容器内连接数据库示例：
```bash
docker compose exec patch-merge-system psql -h 127.0.0.1 -p 5557 -U patchmerge -d patchmerge
```
## Codex CLI 与 CC Switch CLI
检查版本：
```bash
docker run --rm patch-merge-system:0.2.0 codex --version
docker run --rm patch-merge-system:0.2.0 cc-switch --version
```
CC Switch CLI 和 Codex 的持久化目录不再使用独立命名卷，统一放在 `patch-merge-workspace` 下：
- CC Switch 配置库：`patch-merge-workspace/cc-switch-home` → 容器内 `CC_SWITCH_CONFIG_DIR=/workspace/cc-switch-home`
- Codex live 配置：`patch-merge-workspace/codex-home` → 容器内 `CODEX_HOME=/workspace/codex-home`
查看 Codex 供应商：
```bash
docker compose exec --user patchmerge patch-merge-system cc-switch --app codex provider list
```
进入 CC Switch TUI：
```bash
docker compose exec --user patchmerge patch-merge-system cc-switch
```
切换供应商示例：
```bash
docker compose exec --user patchmerge patch-merge-system cc-switch --app codex provider switch
```
也可以用 CC Switch 临时启动 Codex，不切换全局供应商：
```bash
docker compose exec --user patchmerge patch-merge-system cc-switch start codex
```
不要在 Dockerfile、Compose 文件或 Git 中写入 `OPENAI_API_KEY` 或第三方供应商 key。如果自动化环境必须注入密钥，请使用 Docker/Kubernetes secret。
## 数据与停止
所有 Patch 合并系统持久化数据只使用一个 Docker 命名卷：
- `patch-merge-workspace` external named volume → `D:\Program Files\QwenPaw\data\workspaces\patch-merge-dev-agent\patch-merge-system-workspace`
- PostgreSQL 数据：`/workspace/postgres-data/18/docker`
- Codex 配置：`/workspace/codex-home`
- CC Switch CLI 配置：`/workspace/cc-switch-home`
- Patch 隔离工作区/仓库：`/workspace/repo`
- Patch、报告、运行产物预留目录：`/workspace/patches`、`/workspace/reports`、`/workspace/runs`
- 停止服务：`docker compose down`
- `docker compose down -v` 会尝试删除 Compose 管理的 volume；当前 `patch-merge-workspace` 是 external volume，不会被 Compose 自动删除。删除命名卷或宿主机工作区目录都属于破坏性操作，执行前先备份并确认。
## 当前范围
这一版已经具备 Patch 合并平台的业务骨架：邮箱监听配置入口、模拟 patch 邮件导入、Codex 需求确认单生成占位、人工审核转工单、工单执行演练、报告生成、运行事件、智能体设置、信使服务和系统设置。
仍待后续迭代实现的真实能力包括：IMAP 邮件监听与附件解析、patch 文件持久化与安全校验、隔离工作区/临时分支、`git apply --check`、`git apply --3way`、冲突处理、真实 commit/push、通知实际发送、权限控制、任务队列和回滚。