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:
82
README.md
82
README.md
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user