安装部署

部署方式

方式一：Docker Compose（推荐）

git clone <your-repo-url> forgexa
cd forgexa
docker compose up -d

启动服务：

服务	端口	说明
api	8000	FastAPI 后端
web	3000	React 前端（Nginx）
postgres	5432	PostgreSQL 16 + pgvector
redis	6379	Redis 7（事件总线）
minio	9000/9001	MinIO（制品存储）
pgadmin	5050	pgAdmin（可选）

方式二：宿主机模式

开发环境下，直接在宿主机运行后端和前端：

# 后端
cd backend
pip install -e ".[dev]"
uvicorn app.main:app --reload --port 8000

# 前端
cd frontend
npm install
npm run dev

运行时守护进程配置

守护进程可在任何安装了 AI Agent 的机器上运行。

前置条件

安装至少一个 AI 编码 Agent：

# Claude Code（推荐）
npm install -g @anthropic-ai/claude-code

# 或 Codex
npm install -g @openai/codex

# 或 OpenCode
go install github.com/opencode-ai/opencode@latest

# 或 MiMo Code（显式选择，v0.1.14+）
curl -fsSL https://mimo.xiaomi.com/install | bash
mimo --version

# 或 Qwen Code（显式 Runtime 选择，v0.24.1+）
npm install -g @qwen-code/qwen-code
qwen --version
qwen sandbox --sandbox

# 或 CodeBuddy（显式 Runtime 选择，v2.156.0+）
npm install -g @tencent-ai/codebuddy-code
codebuddy --version

# 或 Qoder CLI（显式 Runtime 选择，v1.1.59+）
curl -fsSL https://qoder.com/install | bash
qoder --version

# 或 TraeCode CLI（显式 Runtime 选择；完成官方登录后使用）
sh -c "$(curl -fsSL https://trae.cn/trae-cli/install_v2.sh)"
traecli --version

# 或 ZCode（显式 Runtime 选择；使用 app-server Protocol）
zcode --version
# 构建批准（推荐）：一条命令把实际 zcode 二进制的 fingerprint 写入持久 allowlist
# （~/.forgexa/zcode-allowed-sha256，GUI 启动的桌面/守护进程同样可见，无需重启）：
forgexa zcode approve-build
# 备选：仅对能读到该 export 的进程生效：
export FORGEXA_ZCODE_ALLOWED_SHA256="<approved-zcode-sha256>"
# 可选：为 Forgexa 的 ZCode Protocol profile 指定独立目录
export FORGEXA_ZCODE_HOME="$HOME/.forgexa/zcode"
# 首次使用需在 Forgexa 专用 profile 中完成一次官方登录（浏览器 OAuth，不共享桌面版凭据）：
HOME="$HOME/.forgexa/zcode" zcode login
# 如该专用 profile 尚未持久化默认模型，显式指定 ZCode 选择器格式的模型：
export FACTORY_ZCODE_MODEL="<providerId/modelId>"

提示：macOS 从 Dock/Finder 启动的桌面 App 不会继承 shell 的 export。请先在 Terminal 中启动一次 App，或执行 launchctl setenv FORGEXA_ZCODE_ALLOWED_SHA256 "<approved-zcode-sha256>"（重启后需重设）后再启动。

守护进程可发现 13 个集成：Claude Code、Codex、GitHub Copilot、Gemini CLI、OpenCode、Kimi Code、MiMo Code、Qwen Code、CodeBuddy、Qoder CLI、TraeCode CLI、ZCode 与 DeepSeek Harness。6 个为标准自动候选，7 个需显式选择。其他本机 CLI 保留用户管理的认证与配置；Harness 则使用受管运行 home 与外部认证只读引用。TraeCode CLI 与 ZCode 保留原有就绪门禁。

Harness 开发者预览建议全局安装 npm i -g @deepseek-ai/dsh@0.2.0-rc.2，要求 22.x 中的 Node 22.19+ 或 Node 24+。精确构件完成首轮/恢复/取消/隔离验收后，再执行 forgexa agent approve-live deepseek。限于 Desktop/个人 Runtime；macOS 要求 sandbox-exec，Linux 要求可用 bwrap，原生 Windows 与共享池未开放。详见 Harness 配置与限制。

各 Agent 在 macOS / Linux / Windows 三个平台的安装与授权详解（含官网链接与最低版本要求），请参阅《AI Agent 安装指南》。

启动守护进程

# 连接本地/自托管服务时建议设置
export DAEMON_SERVER_URL=http://your-server:8000
export DAEMON_API_TOKEN=your-api-token

# 可选配置
export DAEMON_MAX_CONCURRENT=5         # 最大并行任务数
export DAEMON_POLL_INTERVAL=3          # 轮询间隔（秒）
export DAEMON_WORKSPACES_ROOT=~/.ai-factory/workspaces

# 启动
forgexa daemon start

多服务器模式

单个守护进程可连接多个 API 服务器：

export DAEMON_SERVER_URLS=http://server1:8000,http://server2:8000
forgexa daemon start

CLI 安装

推荐安装独立 CLI 包：

pip install forgexa-cli

# 登录
forgexa login --server http://localhost:8000 --email admin@example.com --password admin123

# 检查守护进程状态
forgexa daemon status

环境变量

API 服务器

变量	默认值	说明
DATABASE_URL	postgresql+asyncpg://...	PostgreSQL 连接串
REDIS_URL	redis://localhost:6379	Redis 连接串
SECRET_KEY	（必需）	JWT 签名密钥

守护进程

变量	默认值	说明
DAEMON_SERVER_URL	https://api.forgexa.net	API 服务器地址
DAEMON_API_TOKEN	（可选）	认证令牌（如已通过 CLI 登录可自动读取）
DAEMON_MAX_CONCURRENT	5	最大并行任务数
DAEMON_POLL_INTERVAL	3	轮询间隔（秒）
DAEMON_ID	主机名	守护进程唯一标识
FACTORY_CLAUDE_MODEL	（无）	覆盖 Claude 模型