Skip to Content
FacetX

部署指南

本指南涵盖 FacetX 应用所有支持的部署方式：本地开发、Docker Compose 以及使用 Kubernetes 管理沙箱的生产环境。

本地开发部署

本地工作流是运行 FacetX 最快的方式，所有服务作为原生进程在你的机器上运行。

make dev

启动的服务：

服务端口描述
Gateway API8001FastAPI 后端 + 嵌入式 Agent 运行时
前端3000Next.js 界面
nginx2026统一反向代理

访问地址：http://localhost:2026 

Docker Compose 部署

Docker Compose 在容器中运行所有服务。适用于更接近生产的本地设置或团队环境。

前置条件

  • Docker（macOS 上的 Docker Desktop 或 OrbStack）
  • 在仓库根目录中已配置的 config.yaml

开发 Compose

# 设置 FacetX 仓库根目录的绝对路径
export FACETX_ROOT=/path/to/FacetX
 
docker compose -f docker/docker-compose-dev.yaml up --build

访问地址：http://localhost:2026 

环境变量

在仓库根目录创建 .env 文件用于存放密钥和运行时配置：

# .env
OPENAI_API_KEY=sk-...
FACETX_ROOT=/absolute/path/to/FacetX
BETTER_AUTH_SECRET=your-secret-here-min-32-chars

docker-compose*.yaml 文件包含 env_file: ../.env 指令，会自动加载该文件。

在部署前始终将 BETTER_AUTH_SECRET 设置为强随机字符串。没有它，前端构建会使用一个公开已知的默认值。

数据持久化

线程数据存储在 backend/.facetx/threads/。在 Docker 部署中，此目录会绑定挂载到 gateway 容器中。

为避免容器重建时数据丢失：

  1. 将 FACETX_ROOT 设置为仓库根目录的绝对路径。
  2. 验证 threads/ 和 skills/ 目录挂载正确。

对于生产环境，使用命名卷或持久化卷声明（PVC）代替主机绑定挂载。

生产部署注意事项

沙箱模式选择

沙箱使用场景
LocalSandboxProvider单用户、受信任的本地工作流
AioSandboxProvider（Docker）多用户、中等隔离需求
E2BSandboxProvider（e2b 云）托管/Serverless、无需运维 Docker/K8s、开箱即用 Jupyter
AioSandboxProvider + K8s Provisioner生产环境、强隔离、多用户

对于有多个并发用户的任何部署，使用基于容器的沙箱，防止用户之间的执行环境相互干扰。

数据库后端

SQLite 适合本地开发和单用户部署，但不适合作为多用户生产环境的数据库后端。

在 SQLite 模式下，FacetX 会把 LangGraph 检查点数据和应用数据写入同一个 facetx.db 文件。WAL 模式可以支持并发读取，但 SQLite 同一时间仍然只有一个写入者。多个用户同时运行 Agent 时，检查点写入和应用写入会竞争同一个文件锁，可能触发 sqlite3.OperationalError: database is locked。

生产环境或任何多用户部署请使用 Postgres：

# .env
DATABASE_URL=postgresql://user:password@postgres:5432/facetx
UV_EXTRAS=postgres
# config.yaml
database:
  backend: postgres
  postgres_url: $DATABASE_URL
 
run_events:
  backend: db

SQLite 部署应限制在本地、单节点或短期评估场景。

K8s Provisioner 配置

配置 Provisioner

在你的 .env 或 compose 覆盖文件中设置必需的环境变量：

K8S_NAMESPACE=FacetX
SANDBOX_IMAGE=enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest
FACETX_ROOT=/absolute/path/to/FacetX

配置沙箱提供者

# config.yaml
sandbox:
  use: FacetX.community.aio_sandbox:AioSandboxProvider
  provisioner_url: http://provisioner:8002

配置数据持久化

对于生产环境，使用 PVC 代替 hostPath 卷：

# 在 .env 或 compose 环境中
USERDATA_PVC_NAME=facetx-userdata-pvc
SKILLS_PVC_NAME=facetx-skills-pvc

当设置 USERDATA_PVC_NAME 时，Provisioner 自动使用子路径（facetx/users/{user_id}/threads/{thread_id}/user-data），每个用户的每个线程在 PVC 中获得自己的目录。

nginx 配置

nginx 将流量路由到前端或 Gateway。/api/langgraph/* 会被重写到 Gateway 的 LangGraph-compatible /api/* 路由，因此不需要单独的 LangGraph upstream。

认证配置

FacetX 应用使用 Better Auth  进行会话管理。在生产环境中：

  1. 将 BETTER_AUTH_SECRET 设置为强随机字符串（最少 32 个字符）。
  2. 将 BETTER_AUTH_URL 设置为你的公开 URL（例如 https://your-domain.com）。
# 生成密钥
openssl rand -base64 32

资源建议

服务最低配置推荐配置
Gateway + Agent 运行时2 vCPU、4 GB RAM4 vCPU、8 GB RAM
前端0.5 vCPU、512 MB1 vCPU、1 GB
沙箱容器（每会话）1 vCPU、1 GB2 vCPU、2 GB

部署后验证

启动后验证部署：

# 检查 Gateway 健康状态
curl http://localhost:8001/health
 
# 通过 nginx 列出配置的模型（验证完整代理链）
curl http://localhost:2026/api/models

正常工作的部署会从每个端点返回 200 响应。/api/models 调用会返回你 config.yaml 中的模型列表。

配置运维与排障
简介