FDE Workbench

面向 Forward Deployed Engineer 团队的开源项目工作台

主要能力 · 首次启动 · 配置说明 · 后端运维 · 开发与测试 · 版本记录

FDE Workbench 覆盖项目、任务、调研、AI 机会、方案、交付文档、文件、用户、Skills、插件和模型配置。它由 Electron 桌面端与 Flask API 组成，业务数据保存在部署者自己的 MySQL、Redis 和文件存储中。

源码包含 macOS Apple Silicon（arm64）DMG 和 Windows x64 NSIS 的构建配置。Windows 构建支持来自社区贡献 PR #1；贡献者报告在 Windows 11 x64 上构建并安装成功，但安装包图标、卸载，以及连接后端后的完整业务流程尚未完成验收。本项目目前不提供已经签名、可直接视为正式发行版的 Windows 安装包，也不承诺其他 Windows 架构或版本的兼容性。

• Node.js 22+ 与 npm 10+
• Python 3.12 或 3.13
• MySQL 8.0+、Redis 7+
• Docker（可选，仅用于快速启动 MySQL/Redis）
• ClamAV、LibreOffice（可选；用于病毒扫描和文档预览/转换）

所有命令都在本仓库根目录执行。

docker compose up -d mysql redis

也可以使用已有服务，并在 server/.env 中填写连接地址。

npm install
python3.12 -m venv server/.venv
server/.venv/bin/pip install -r server/requirements.lock -e 'server[test]'
cp .env.example server/.env

编辑 server/.env，至少将 FDE_JWT_SECRET 换成独立随机值：

python3 -c 'import secrets; print(secrets.token_urlsafe(48))'

cd server
.venv/bin/alembic upgrade head
.venv/bin/flask --app fde_api.app:create_app bootstrap-open-source
cd ..

初始化命令可重复执行，不会覆盖已有用户或业务数据。全新数据库会创建一个必须首次改密的管理员：

初始凭据仅用于空数据库首次进入。登录后必须立即改密；已有任何用户时，初始化命令不会再创建该账号。

分别打开三个终端：

cd server && .venv/bin/flask --app fde_api.app:create_app run --host 127.0.0.1 --port 8010

cd server && .venv/bin/flask --app fde_api.app:create_app worker

cd server && .venv/bin/flask --app fde_api.app:create_app scheduler

npm run dev

登录并完成改密后，管理员进入左侧“系统配置”，设置模型 API、AI Server、微信/ClawBot、扩展市场、存储与安全扫描。模型 API Key 等密钥在后端加密保存且不回显。

无需先配置 AI Key 即可登录和使用项目、任务、调研记录、文件等非 AI 功能；AI 生成、分析和对话等功能需要对应模型服务及 API Key。OSS、微信/ClawBot 等外部集成也需分别配置，并非填写一个 AI Key 就能开启全部功能。所有功能均要求后端及其数据库、Redis 等基础服务正常运行。

工作台运行后可变的集成配置全部由管理员在“系统配置”或“AI 与扩展”中管理。以下是应用启动前的基础设施配置，服务尚未启动时无法通过界面设置：

不要在提交、issue、日志或截图中暴露 .env。生产环境切换 FDE_JWT_SECRET 前应先在系统配置中重新录入所有加密密钥。

cd server
.venv/bin/alembic current
.venv/bin/alembic upgrade head

升级前应同时备份 MySQL 和文件存储。迁移文件位于 server/migrations/versions/，不得修改已发布迁移，应新增迁移。

• GET /health/live：进程存活
• GET /health/ready：数据库、Redis 等依赖就绪状态

• 使用 Gunicorn 承载 fde_api.wsgi:app，并独立运行 worker 与 scheduler。
• API 仅暴露在 HTTPS 反向代理之后；不要将 Flask 开发服务器用于生产。
• MySQL、Redis、OSS 使用独立最小权限账号；限制网络访问来源。
• 本地文件存储目录、数据库和管理员配置密文必须一起备份。
• 桌面安装包默认连接 http://127.0.0.1:8010。远程部署时，在打包前设置受信任的 HTTPS API 地址并修改 desktop/package.json 的 build.extraMetadata.fdeApiUrl。
• 开源版没有内置更新中心；版本升级由部署者通过代码发布、数据库迁移和重新打包完成。

npm run typecheck
npm run test:desktop
npm run test:server
npm run test:operations

完整 npm test 需要 MySQL 和 Redis。端到端测试只允许使用数据库名精确为 fde_workbench_test 的测试库：

mysql -uroot -p -e "CREATE DATABASE fde_workbench_test CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci"
FDE_E2E_DATABASE_URL='mysql+pymysql://USER:PASSWORD@127.0.0.1:3306/fde_workbench_test' npm run test:e2e

macOS Apple Silicon（arm64）DMG：

npm run package:mac

Windows x64 NSIS 安装包（在 Windows 构建环境执行）：

npm run package:win

桌面安装包只包含客户端；使用前仍需按上文部署后端、MySQL 和 Redis。默认 API 地址为 http://127.0.0.1:8010，连接远程后端时须在打包前配置 desktop/package.json 中的 build.extraMetadata.fdeApiUrl 为受信任的 HTTPS 地址。

package:mac 使用本地临时签名，不是已签名公证的正式 macOS 发行流程。正式外发应使用发行者自己的 Developer ID 完成签名、公证、装订及 Gatekeeper 验收。Windows 构建脚本能生成安装包，但构建或安装成功不等于发行验收；公开分发前应完成代码签名，并在真实 Windows 环境验证安装包图标、安装、启动、登录及后端连接、主要功能和卸载。**未签名安装包不能当作已验收发行版发布或宣传。**本仓库不包含签名证书、公证凭据或历史安装包。

• 界面及本 README 页首使用 desktop/src/renderer/src/assets/logo.png。更换 Logo 时，直接用同名 PNG 替换该文件，再重新构建客户端。
• macOS 安装图标由 npm run package:mac 调用 icon:mac，根据上述 Logo 生成 desktop/build/icon.png 和 desktop/build/icon.icns。
• Windows 应用图标使用 desktop/build/icon.png，NSIS 安装及卸载图标使用 desktop/build/icon.ico。更换 Logo 后还需用新图标重新生成并替换 .ico；仅替换界面 Logo 不会自动更新 Windows 安装图标。

• 仓库中不应出现真实客户、账号、项目、调研、文档、附件或模型对话数据。
• .gitignore 已排除密钥、日志、存储目录、依赖和构建产物，但提交前仍应执行秘密扫描。
• 初始管理员强制改密；生产环境应设置强密码、HTTPS、备份和访问审计。
• 密钥不经 API 回显。数据库泄露防护仍依赖安全保存 FDE_JWT_SECRET 与数据库访问控制。
• 漏洞报告方式见 SECURITY.md。

desktop/     Electron 主进程、预加载层、React UI 与桌面测试
server/      Flask API、Alembic 迁移、后台任务与服务端测试
resources/   通用、无客户数据的文档模板
scripts/     本地开发、测试和打包脚本
tests/       端到端与运维契约测试

贡献流程见 CONTRIBUTING.md。代码采用 MIT License；项目名称、Logo 和第三方商标不因代码许可而自动授予商标使用权。第三方依赖遵循其各自许可证。