zhi/HarborForge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge docs/readme-refresh into main

Browse Source 
Rewrite top-level README (full 7-submodule map, corrected architecture/
ports/model, security notes). No conflicts: remote commits touched only
submodule pointers, this branch only README.md.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
h z
2026-05-16 17:54:09 +01:00
parent e8c7f36950 d69bd5213c
commit 05f1af6c0e
1 changed files with 72 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

117
README.md
View File

@@ -1,34 +1,45 @@
# HarborForge
Agent/人类协同任务管理平台
Agent / 人类协同任务管理平台 —— 用严格的状态机管理 提案 → 里程碑 → 任务 的完整生命周期，配套 CLI、监控与 OpenClaw 集成。
## 项目结构
本仓库是 umbrella 仓库，所有组件以 git 子模块形式组织：
```
HarborForge/
├── HarborForge.Backend/ # 后端 (FastAPI + MySQL)
├── HarborForge.Frontend/ # 前端 (React + Vite)
├── docker-compose.yml # Docker 部署配置
├── nginx-host.conf.example # 宿主机 nginx 配置示例
└── .env.example # 环境变量模板
├── AbstractWizard/ # Go，安全初始化服务（SSH 隧道，端口 8080）
├── HarborForge.Backend/ # Python/FastAPI，核心 REST API + RBAC（端口 8000）
├── HarborForge.Frontend/ # React + TypeScript + Vite，单页前端（端口 3000）
├── HarborForge.Cli/ # Go，命令行客户端 `hf`
├── HarborForge.Monitor/ # Go，主机遥测客户端（可选本地 bridge 9100）
├── HarborForge.OpenclawPlugin/ # Node，OpenClaw 插件 `harbor-forge`
├── HarborForge.Test/ # 集成测试（后端 pytest / 前端 Playwright）
├── docker-compose.yml # Docker 编排配置
├── nginx-host.conf.example # 宿主机 nginx 配置示例
└── .env.example # 环境变量模板
```
## 快速开始
```bash
# 克隆并初始化子模块
git clone https://git.hangman-lab.top/zhi/HarborForge.git
# 克隆并初始化所有子模块
git clone --recurse-submodules https://git.hangman-lab.top/zhi/HarborForge.git
cd HarborForge
# 若已克隆但未初始化子模块：
git submodule update --init --recursive
# 配置环境变量（不要使用默认值，见“安全”一节）
cp .env.example .env
# 编辑 .env，至少设置强随机 SECRET_KEY 与数据库口令
# 启动服务
docker compose up -d
```
## 首次部署 — 初始化向导
HarborForge 使用 [AbstractWizard](https://git.hangman-lab.top/hzhang/AbstractWizard) 进行安全初始化。
Wizard 仅监听 `127.0.0.1`，必须通过 SSH 隧道访问。
HarborForge 使用 [AbstractWizard](./AbstractWizard) 进行安全初始化。Wizard 仅监听 `127.0.0.1`，必须通过 SSH 隧道访问。
```bash
# 1. SSH 隧道映射 wizard 端口到本地
@@ -37,65 +48,81 @@ ssh -L 18080:127.0.0.1:18080 user@your-server
# 2. 浏览器访问前端（或通过宿主机 nginx）
# 前端检测到后端未就绪 → 自动跳转初始化向导
# 3. 在向导中配置:
# - 数据库连接信息
# - 管理员账号
# - 默认项目（可选）
# 3. 在向导中配置：数据库连接、管理员账号、默认项目（可选）
# 4. 配置保存后，后端自动检测到配置并启动
# 刷新页面 → 进入登录界面
# 4. 配置保存后，后端自动检测到配置并启动；刷新页面 → 登录界面
```
### 启动流程
```
docker compose up
├── mysql → 数据库启动
├── wizard → AbstractWizard 启动 (127.0.0.1:18080)
├── backend → 等待配置文件... (轮询 /config/harborforge.json)
└── frontend → 检测后端状态
├── 后端未就绪 → 显示初始化向导 (SSH 隧道连 wizard)
└── 后端就绪 → 正常登录界面
├── mysql → 数据库启动
├── wizard → AbstractWizard 启动（127.0.0.1，SSH 隧道访问）
├── backend → 阻塞等待配置文件（轮询 /config/harborforge.json）
└── frontend → 检测后端状态
├── 后端未就绪 → 显示初始化向导（SSH 隧道连 wizard）
└── 后端就绪 → 正常登录界面
```
### 安全模型
- Wizard 端口绑定 `127.0.0.1`，不暴露到外部网络
- 初始化必须通过 SSH 隧道完成（与 AbstractWizard 安全模型一致）
- 配置完成后 Wizard 自动切换为只读模式
- 配置通过 Docker volume 共享给后端（不走网络）
- Wizard 端口绑定 `127.0.0.1`，不暴露到外部网络；初始化必须经 SSH 隧道完成。
- 配置通过 Docker volume 共享给后端（不走网络），后端以只读方式挂载。
## 部署架构
```
宿主机 nginx (80/443)
├── / → frontend (Docker, port 3000)
└── /api/ → backend (Docker, port 8000)
├── / → frontend (Docker, 端口 3000)
└── /api/ → backend (Docker, 端口 8000)
Docker 内部 (不暴露):
wizard (127.0.0.1:18080) → 配置管理，SSH 隧道访问
wizard_config volume → wizard 写入，backend 读取
Docker 内部（不对外）:
wizard (127.0.0.1) → 配置管理，SSH 隧道访问
wizard_config vol → wizard 写入，backend 只读读取
mysql (127.0.0.1) → 数据持久化
```
## 子模块
- [HarborForge.Backend](https://git.hangman-lab.top/zhi/HarborForge.Backend) - FastAPI 后端 API
- [HarborForge.Frontend](https://git.hangman-lab.top/zhi/HarborForge.Frontend) - React 前端
| 子模块 | 技术栈 | 作用 |
|--------|--------|------|
| [AbstractWizard](./AbstractWizard) | Go | 首次安装向导，安全写配置（原子写 + 备份），init/readonly 模式 |
| [HarborForge.Backend](./HarborForge.Backend) | Python / FastAPI / SQLAlchemy / MySQL | 核心 API：用户、项目、任务、里程碑、提案、RBAC、Webhook、工时、通知 |
| [HarborForge.Frontend](./HarborForge.Frontend) | React 18 / TS / Vite | SPA，~20 页面；自动检测未初始化 → 引导安装向导 |
| [HarborForge.Cli](./HarborForge.Cli) | Go | 权限感知命令行客户端 `hf` |
| [HarborForge.Monitor](./HarborForge.Monitor) | Go | 独立主机遥测客户端，心跳上报 |
| [HarborForge.OpenclawPlugin](./HarborForge.OpenclawPlugin) | Node / TS | OpenClaw 插件，桥接遥测，可安装 `hf` 技能与日历调度 |
| [HarborForge.Test](./HarborForge.Test) | pytest / Playwright | 后端与前端集成测试 |
## 核心业务模型
- **里程碑**：`open → freeze → undergoing → completed`（freeze 时须恰好 1 个 release 任务）
- **任务**（issue / story / test / maintenance / research / review / resolution）：`pending → open → undergoing → completed`，完成须带评论
- **提案**：用户提 propose → 管理者 accept → 自动在里程碑内创建 feature story 任务；reject 可重开
- **RBAC**：细粒度权限 + 项目角色层级（guest < viewer < member < dev < mgr < admin）
## 端口
| 服务 | 默认端口 | 绑定 | 环境变量 |
| 服务 | 容器端口 | 绑定 | 环境变量 |
|------|----------|------|----------|
| Frontend | 3000 | 0.0.0.0 | `FRONTEND_PORT` |
| Backend | 8000 | 0.0.0.0 | `BACKEND_PORT` |
| MySQL | 3306 | 127.0.0.1 | `MYSQL_PORT` |
| Wizard | 18080 | 127.0.0.1 | `WIZARD_PORT` |
| Frontend | 3000 | 见 compose | `FRONTEND_PORT` |
| Backend | 8000 | 见 compose | `BACKEND_PORT` |
| MySQL | 3306 | 127.0.0.1 | `MYSQL_PORT` |
| Wizard | 8080 | 127.0.0.1 | `WIZARD_PORT` |
## 前端页面
> SSH 隧道示例使用本地端口 `18080` 转发到服务器 wizard。
- 🔧 初始化向导 — 首次部署配置（SSH 隧道）
- 📊 仪表盘 — 统计概览
- 📋 Issues — 创建、列表、详情、状态变更、评论
- 📁 项目 — 项目管理、成员、关联 issue
- 🏁 里程碑 — 进度追踪、完成百分比
- 🔔 通知 — 实时通知中心、未读计数
## 安全
部署前务必：
- **设置强随机 `SECRET_KEY`**（如 `openssl rand -hex 32`）。后端在检测到弱/默认/过短密钥时会拒绝启动。
- 不要使用 `.env.example` 中的占位口令；为 MySQL 设置强口令。
- 不要将含真实密钥的 `.env` 提交进版本库。
后端的鉴权/RBAC/SSRF 加固详见 [HarborForge.Backend 的 README](./HarborForge.Backend) “Security” 一节。
## 前端
前端采用集中式自定义设计系统（“Foundry Deck” 工业主题），细节见 [HarborForge.Frontend 的 README](./HarborForge.Frontend)。