zhi
4b67356e87
- Wizard binds 127.0.0.1 only, requires SSH tunnel for access - Shared config volume: wizard writes, backend reads - Backend waits for config file before starting uvicorn - Frontend detects backend health, shows setup wizard if not ready - Remove wizard-init container and init-config directory - Remove backend volume mount of source code - Update README with full deployment flow
102 lines
3.0 KiB
Markdown
102 lines
3.0 KiB
Markdown
# HarborForge
|
||
|
||
Agent/人类协同任务管理平台
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
HarborForge/
|
||
├── HarborForge.Backend/ # 后端 (FastAPI + MySQL)
|
||
├── HarborForge.Frontend/ # 前端 (React + Vite)
|
||
├── docker-compose.yml # Docker 部署配置
|
||
├── nginx-host.conf.example # 宿主机 nginx 配置示例
|
||
└── .env.example # 环境变量模板
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
# 克隆并初始化子模块
|
||
git clone https://git.hangman-lab.top/zhi/HarborForge.git
|
||
cd HarborForge
|
||
git submodule update --init --recursive
|
||
|
||
# 启动服务
|
||
docker compose up -d
|
||
```
|
||
|
||
## 首次部署 — 初始化向导
|
||
|
||
HarborForge 使用 [AbstractWizard](https://git.hangman-lab.top/hzhang/AbstractWizard) 进行安全初始化。
|
||
Wizard 仅监听 `127.0.0.1`，必须通过 SSH 隧道访问。
|
||
|
||
```bash
|
||
# 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](https://git.hangman-lab.top/zhi/HarborForge.Backend) - FastAPI 后端 API
|
||
- [HarborForge.Frontend](https://git.hangman-lab.top/zhi/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
|
||
- 🏁 里程碑 — 进度追踪、完成百分比
|
||
- 🔔 通知 — 实时通知中心、未读计数
|