HarborForge

Agent/人类协同任务管理平台

项目结构

HarborForge/
├── HarborForge.Backend/    # 后端 (FastAPI + MySQL)
├── HarborForge.Frontend/   # 前端 (React + Vite)
├── docker-compose.yml      # Docker 部署配置
├── nginx-host.conf.example # 宿主机 nginx 配置示例
└── .env.example            # 环境变量模板

快速开始

# 克隆并初始化子模块
git clone https://git.hangman-lab.top/zhi/HarborForge.git
cd HarborForge
git submodule update --init --recursive

# 启动服务
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:18080)
  ├── backend     → 等待配置文件... (轮询 /config/harborforge.json)
  └── frontend    → 检测后端状态
                    ├── 后端未就绪 → 显示初始化向导 (SSH 隧道连 wizard)
                    └── 后端就绪   → 正常登录界面

安全模型

• Wizard 端口绑定 127.0.0.1，不暴露到外部网络
• 初始化必须通过 SSH 隧道完成（与 AbstractWizard 安全模型一致）
• 配置完成后 Wizard 自动切换为只读模式
• 配置通过 Docker volume 共享给后端（不走网络）

部署架构

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

Docker 内部 (不暴露):
  wizard (127.0.0.1:18080) → 配置管理，SSH 隧道访问
  wizard_config volume     → wizard 写入，backend 读取

子模块

• HarborForge.Backend - FastAPI 后端 API
• HarborForge.Frontend - React 前端

端口

服务	默认端口	绑定	环境变量
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

前端页面

• 🔧 初始化向导 — 首次部署配置（SSH 隧道）
• 📊 仪表盘 — 统计概览
• 📋 Issues — 创建、列表、详情、状态变更、评论
• 📁 项目 — 项目管理、成员、关联 issue
• 🏁 里程碑 — 进度追踪、完成百分比
• 🔔 通知 — 实时通知中心、未读计数