FW Builder v3

固件自动化构建平台 — 多用户 + Authentik OIDC + Web 管理界面

功能特性

• Web 管理界面：仪表盘 / 工具链 / 工序链 / URL 规则 / 触发器 / 任务 / 用户 / 认证
• 7 种内置工具链模板：Keil MDK / GCC ARM / Make / CMake / ESP-IDF / IAR / SSH 远程
• 三种 Trigger：Webhook（支持 URL 通配） / Manual（手动点击） / Cron（定时调度）
• 多用户 + Authentik OIDC：Authorization Code + PKCE，JIT 自动注册，角色映射
• Webhook Token 旁路：给 CI / n8n 使用，不走 OIDC
• 钉钉 / 企微通知：构建结果自动推送
• SSH 远程执行：通过 paramiko 在 Linux 编译机跑命令
• 暗色主题中文界面

快速开始

# 1. 安装依赖
pip install -r requirements.txt

# 2. 写入演示数据（首次运行）
python init_demo.py

# 3. 启动
python main.py

浏览器打开 http://127.0.0.1:8000

目录结构

fw-builder-v3/
├── main.py              # 启动入口（FastAPI lifespan）
├── config_store.py      # YAML 配置读写 + 7 模板注入
├── models_user.py       # 多用户数据模型 + JIT 注册
├── auth_config.py       # 认证配置（环境变量覆盖）
├── auth.py              # OIDC 核心（登录/回调/登出/依赖注入）
├── routes_api.py        # REST API（工具链/工序链/规则/任务/触发器）
├── routes_ui.py         # Web 管理页面路由
├── webhook_routes.py    # /hook/* 触发入口（绕过 /api 前缀）
├── routes_users.py      # 用户管理 API
├── builder.py           # 核心引擎（URL匹配→工序链→通知）
├── triggers.py          # APScheduler 定时调度
├── ssh_client.py        # paramiko SSH 远程执行
├── notifier.py          # 钉钉/企微通知
├── toolchains.py        # 7 种内置工具链模板
├── init_demo.py         # 演示数据初始化
├── requirements.txt     # Python 依赖
├── config.yaml          # 自动生成的主配置
├── _users.yaml          # 自动生成的用户存储
└── templates/
    ├── base.html        # 布局框架（暗色主题）
    ├── index.html       # 仪表盘
    ├── toolchains.html  # 工具链管理
    ├── pipelines.html   # 工序链编排
    ├── url_rules.html   # URL 路由规则
    ├── triggers.html    # 触发器管理
    ├── tasks.html       # 任务列表
    ├── task_detail.html # 任务详情+日志
    ├── users_page.html  # 用户管理
    └── auth_page.html   # 认证设置

认证模式

None 模式（默认）

单用户，无鉴权。所有 API 和页面直接可用。

OIDC 模式（Authentik）

1. 在 Authentik 创建 OIDC Provider（Confidential）
2. 设置 Redirect URI：http://127.0.0.1:8000/auth/callback
3. 编辑 config.yaml 的 auth 段，或设置环境变量
4. 重启 FW Builder
5. 访问 /login → 跳转 Authentik → 首次登录自动建号

环境变量

$env:OIDC_ENABLED="true"
$env:OIDC_ISSUER="https://auth.company.com/application/o/fw-builder/"
$env:OIDC_CLIENT_ID="xxx"
$env:OIDC_CLIENT_SECRET="xxx"
$env:WEBHOOK_TOKEN="super-secret-ci-token"

角色映射

Authentik Group	FW Builder Role
fw-admin / admin	admin（全部权限）
fw-viewer	viewer（仅查看）
其他	member（查看+触发）

Webhook 触发

# 精确匹配
curl -X POST http://127.0.0.1:8000/hook/build/stm32/release

# 通配匹配（/hook/build/* → STM32 工序链）
curl -X POST http://127.0.0.1:8000/hook/build/esp32/ota

# 带 Token 鉴权
curl -H "X-Webhook-Token: super-secret" \
     -X POST http://127.0.0.1:8000/hook/build/stm32

定时触发（Cron）

在 Web 界面「触发器」页添加，表达式格式：分 时 日 月 周

表达式	含义
0 9 * * *	每天 9:00
0 */2 * * *	每 2 小时
30 8 * * 1-5	工作日 8:30
*/5 * * * *	每 5 分钟

注册为 Windows 服务

推荐使用 nssm：

nssm install fw-builder
# Path: C:\Python312\python.exe
# Arguments: main.py
# Startup directory: D:\fw-builder-v3
nssm start fw-builder

运行测试

pip install pytest
python -m pytest tests/ -q

测试全部离线运行（不需要真实 Authentik）：

• test_auth.py — PKCE(S256) / 授权 URL / 角色映射
• test_builder.py — URL 通配匹配 / 变量渲染 / 本地 & SSH 执行
• test_config_users.py — 配置合并 / CRUD / 用户 JIT 注册
• test_api.py — 全部 /api 与 /page 端点
• test_oidc_flow.py — OIDC 回调 / 会话 / Webhook 鉴权（monkeypatch 打桩）

安全建议

1. 生产环境改 config.yaml 中 server.host 为 127.0.0.1（仅本机）
2. 配置 Webhook Token（即使只在本机，也建议设置）
3. 限制 CORS：将 server.cors_origins 从 ["*"] 改为具体域名（如 ["https://fw.company.com"]）。 注意：含 * 时按规范会自动禁用凭据（cookie）跨域，只有配置具体域名才会放行带凭据请求。
4. 反向代理 + HTTPS（Traefik / Nginx）放在 FW Builder 前面
5. Authentik ForwardAuth 可做额外一层防护

License

MIT