gxfde / fde-workbench

FDE Workbench 
 面向 Forward Deployed Engineer 团队的开源项目工作台 
 主要能力 ·
 首次启动 ·
 配置说明 ·
 后端运维 ·
 开发与测试 ·
 版本记录 
---
FDE Workbench 覆盖项目、任务、调研、AI 机会、方案、交付文档、文件、用户、Skills、插件和模型配置。它由 Electron 桌面端与 Flask API 组成，业务数据保存在部署者自己的 MySQL、Redis 和文件存储中。
| 当前版本 | 你需要知道的事 |
| --- | --- |
| 桌面平台 | macOS Apple Silicon（arm64）DMG 与 Windows x64 NSIS 构建配置；Windows 尚未完成发行验收 |
| 发布内容 | 提供源码，不附带已签名、已验收的安装包；不包含客户端自更新 |
| 首次登录 | 空数据库初始化后使用 `admin` / `ChangeMe123!`，首次登录强制改密 |
| AI 功能 | 基础功能无需 AI Key；模型及其他外部集成由管理员分别配置 |
> [!IMPORTANT]
> 本仓库是清理后的开源发行版，不包含生产数据库、客户资料、运行日志、对象存储文件、访问凭据、安装包或发布备份。
> [!WARNING]
> **商用前请独立核验。**本项目以 *vibe coding*（AI 辅助快速开发）方式构建。开源发布不代表已经完成全面的安全审计、合规评估、性能压测或生产级验收，也不保证适用于特定业务。商用、对外服务或处理真实客户数据前，请审查源码及依赖，并验证权限隔离、数据安全、文件处理、模型输出、备份恢复和升级迁移；同时完成适用的法律与行业合规评估。不要直接将默认配置或初始管理员凭据用于生产。
## 主要能力
| 项目协作 | 调研与交付 | AI 与管理 |
| --- | --- | --- |
| 项目、成员、任务、甘特关系和阶段管理 | 调研对象、调研表、备忘录、AI 机会和方案设计 | AI 模型、Skills、插件、AI Server、微信/ClawBot 集成 |
| 项目负责人、FDE 工程师、查看者等角色权限 | 文档模板、交付文档、版本和项目文件管理 | 管理员配置模型服务、扩展市场、对象存储和 ClamAV |
## 平台支持
源码包含 **macOS Apple Silicon（arm64）DMG** 和 **Windows x64 NSIS** 的构建配置。Windows 构建支持来自社区贡献 PR #1；贡献者报告在 Windows 11 x64 上构建并安装成功，但安装包图标、卸载，以及连接后端后的完整业务流程尚未完成验收。本项目目前不提供已经签名、可直接视为正式发行版的 Windows 安装包，也不承诺其他 Windows 架构或版本的兼容性。
## 技术架构
| 层 | 技术 | 说明 |
| --- | --- | --- |
| 桌面端 | Electron、React、TypeScript、electron-vite | 通过受限 IPC 调用后端 API |
| API | Python 3.12/3.13、Flask、SQLAlchemy、Alembic | 认证、权限和业务接口 |
| 数据 | MySQL 8、Redis 7 | 主数据、任务队列与调度 |
| 文件 | 本地目录或兼容 Aliyun OSS 的对象存储 | 由管理员在工作台配置 |
| 后台进程 | Flask CLI worker / scheduler | 文件处理、异步任务与自动化 |
## 环境要求
- Node.js 22+ 与 npm 10+
- Python 3.12 或 3.13
- MySQL 8.0+、Redis 7+
- Docker（可选，仅用于快速启动 MySQL/Redis）
- ClamAV、LibreOffice（可选；用于病毒扫描和文档预览/转换）
## 首次启动
所有命令都在本仓库根目录执行。
### 1. 启动 MySQL 和 Redis
 [code] 
也可以使用已有服务，并在 `server/.env` 中填写连接地址。
### 2. 安装依赖并创建启动配置
 [code] 
编辑 `server/.env`，至少将 `FDE_JWT_SECRET` 换成独立随机值：
 [code] 
### 3. 建库、迁移与初始化
 [code] 
初始化命令可重复执行，不会覆盖已有用户或业务数据。全新数据库会创建一个必须首次改密的管理员：
| 项目 | 初始值 |
| --- | --- |
| 用户名 | `admin` |
| 密码 | `ChangeMe123!` |
| 首次登录 | 强制修改密码 |
初始凭据仅用于空数据库首次进入。登录后必须立即改密；已有任何用户时，初始化命令不会再创建该账号。
### 4. 启动后端
分别打开三个终端：
 [code] 
 [code] 
 [code] 
### 5. 启动桌面端
 [code] 
登录并完成改密后，管理员进入左侧“系统配置”，设置模型 API、AI Server、微信/ClawBot、扩展市场、存储与安全扫描。模型 API Key 等密钥在后端加密保存且不回显。
无需先配置 AI Key 即可登录和使用项目、任务、调研记录、文件等非 AI 功能；AI 生成、分析和对话等功能需要对应模型服务及 API Key。OSS、微信/ClawBot 等外部集成也需分别配置，并非填写一个 AI Key 就能开启全部功能。所有功能均要求后端及其数据库、Redis 等基础服务正常运行。
## 配置边界
工作台运行后可变的集成配置全部由管理员在“系统配置”或“AI 与扩展”中管理。以下是应用启动前的基础设施配置，服务尚未启动时无法通过界面设置：
| 环境变量 | 用途 |
| --- | --- |
| `FDE_DATABASE_URL` | MySQL SQLAlchemy URL |
| `FDE_REDIS_URL` | Redis URL |
| `FDE_JWT_SECRET` | JWT 签名及本地密钥加密根材料，至少 32 字符 |
| `FDE_API_HOST` / `FDE_API_PORT` | API 监听地址和端口 |
| `FDE_ENV` | `development`、`test` 或 `production` |
| `FDE_DESKTOP_API_URL` | 开发态桌面端连接的 API 地址 |
不要在提交、issue、日志或截图中暴露 `.env`。生产环境切换 `FDE_JWT_SECRET` 前应先在系统配置中重新录入所有加密密钥。
## 后端运维
### 数据库迁移
 [code] 
升级前应同时备份 MySQL 和文件存储。迁移文件位于 `server/migrations/versions/`，不得修改已发布迁移，应新增迁移。
### 健康检查
- `GET /health/live`：进程存活
- `GET /healt