HarborForge

Agent / 人类协同任务管理平台 —— 用严格的状态机管理 提案 → 里程碑 → 任务 的完整生命周期，配套 CLI、监控与 OpenClaw 集成。

项目结构

本仓库是 umbrella 仓库，所有组件以 git 子模块形式组织：

HarborForge/
├── 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                # 环境变量模板

快速开始

# 克隆并初始化所有子模块
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 进行安全初始化。Wizard 仅监听 127.0.0.1，必须通过 SSH 隧道访问。

# 1. SSH 隧道映射 wizard 端口到本地
ssh -L 18080:127.0.0.1:18080 user@your-server

# 2. 浏览器访问前端（或通过宿主机 nginx）
#    前端检测到后端未就绪 → 自动跳转初始化向导

# 3. 在向导中配置：数据库连接、管理员账号、默认项目（可选）

# 4. 配置保存后，后端自动检测到配置并启动；刷新页面 → 登录界面

启动流程

docker compose up
  ├── mysql    → 数据库启动
  ├── wizard   → AbstractWizard 启动（127.0.0.1，SSH 隧道访问）
  ├── backend  → 阻塞等待配置文件（轮询 /config/harborforge.json）
  └── frontend → 检测后端状态
                 ├── 后端未就绪 → 显示初始化向导（SSH 隧道连 wizard）
                 └── 后端就绪   → 正常登录界面

安全模型

• Wizard 端口绑定 127.0.0.1，不暴露到外部网络；初始化必须经 SSH 隧道完成。
• 配置通过 Docker volume 共享给后端（不走网络），后端以只读方式挂载。

部署架构

宿主机 nginx (80/443)
  ├── /     → frontend (Docker, 端口 3000)
  └── /api/ → backend  (Docker, 端口 8000)

Docker 内部（不对外）:
  wizard (127.0.0.1) → 配置管理，SSH 隧道访问
  wizard_config vol  → wizard 写入，backend 只读读取
  mysql (127.0.0.1)  → 数据持久化

子模块

子模块	技术栈	作用
AbstractWizard	Go	首次安装向导，安全写配置（原子写 + 备份），init/readonly 模式
HarborForge.Backend	Python / FastAPI / SQLAlchemy / MySQL	核心 API：用户、项目、任务、里程碑、提案、RBAC、Webhook、工时、通知
HarborForge.Frontend	React 18 / TS / Vite	SPA，~20 页面；自动检测未初始化 → 引导安装向导
HarborForge.Cli	Go	权限感知命令行客户端 hf
HarborForge.Monitor	Go	独立主机遥测客户端，心跳上报
HarborForge.OpenclawPlugin	Node / TS	OpenClaw 插件，桥接遥测，可安装 hf 技能与日历调度
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	见 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。

安全

部署前务必：

• 设置强随机 SECRET_KEY（如 openssl rand -hex 32）。后端在检测到弱/默认/过短密钥时会拒绝启动。
• 不要使用 .env.example 中的占位口令；为 MySQL 设置强口令。
• 不要将含真实密钥的 .env 提交进版本库。

后端的鉴权/RBAC/SSRF 加固详见 HarborForge.Backend 的 README “Security” 一节。

前端

前端采用集中式自定义设计系统（“Foundry Deck” 工业主题），细节见 HarborForge.Frontend 的 README。