feat: setup wizard via SSH tunnel, config volume architecture

- 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
This commit is contained in:
zhi
2026-03-06 13:47:02 +00:00
parent 6673372532
commit 4b67356e87
6 changed files with 66 additions and 95 deletions

View File

@@ -21,13 +21,50 @@ git clone https://git.hangman-lab.top/zhi/HarborForge.git
cd HarborForge
git submodule update --init --recursive
# 配置环境变量
cp .env.example .env
# 启动服务
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 共享给后端(不走网络)
## 部署架构
```
@@ -35,32 +72,11 @@ docker compose up -d
├── / → frontend (Docker, port 3000)
└── /api/ → backend (Docker, port 8000)
Docker 内部:
wizard (AbstractWizard) → 初始化配置管理
wizard-init → 首次启动上传默认配置
backend → 启动时从 wizard 读取配置,创建 admin 用户等
Docker 内部 (不暴露):
wizard (127.0.0.1:18080) → 配置管理SSH 隧道访问
wizard_config volume → wizard 写入backend 读取
```
前端 Docker 容器不包含 nginx使用轻量的 `serve` 提供静态文件。
API 代理由宿主机 nginx 统一处理。
### AbstractWizard 初始化
首次部署时,`wizard-init` 会将 `init-config/harborforge.json` 上传到 AbstractWizard。
后端启动时自动从 AbstractWizard 读取配置并创建 admin 用户和默认项目。
修改初始化配置:
```bash
# 直接编辑 init-config/harborforge.json首次部署前
# 或通过 AbstractWizard API 修改(部署后)
curl -X PATCH http://localhost:18080/api/v1/config/harborforge.json \
-d '{"admin": {"password": "new_secure_password"}}'
```
### 宿主机 nginx 配置
参考 `nginx-host.conf.example`,复制到 `/etc/nginx/sites-available/` 并修改域名。
## 子模块
- [HarborForge.Backend](https://git.hangman-lab.top/zhi/HarborForge.Backend) - FastAPI 后端 API
@@ -68,14 +84,16 @@ curl -X PATCH http://localhost:18080/api/v1/config/harborforge.json \
## 端口
| 服务 | 默认端口 | 环境变量 |
|------|----------|----------|
| Frontend | 3000 | `FRONTEND_PORT` |
| Backend | 8000 | `BACKEND_PORT` |
| MySQL | 3306 | `MYSQL_PORT` |
| 服务 | 默认端口 | 绑定 | 环境变量 |
|------|----------|------|----------|
| 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