Skip to Content
FacetX

运维与排障

本页面涵盖运行 FacetX 应用的操作信息：日志记录、常见问题和维护任务。

日志

FacetX 应用在 logs/ 目录中写入每个服务的日志：

文件内容
logs/gateway.logAPI 请求/响应、Agent 运行时和 Gateway 错误
logs/frontend.logNext.js 服务器日志
logs/nginx.log代理访问和错误日志

实时追踪日志：

tail -f logs/gateway.log     # 查看 API 请求和 Agent 活动

调整日志级别：

# config.yaml
log_level: debug # debug | info | warning | error

健康检查

FacetX 暴露健康检查端点：

# Gateway 健康状态
curl http://localhost:8001/health
 
# 通过 nginx 完整代理链验证
curl http://localhost:2026/api/models

配置升级

当 config.yaml schema 更新时（由 config_version 字段标识），运行：

make config-upgrade

这将 config.example.yaml 中的新字段合并到你现有的 config.yaml 中，而不覆盖你的自定义内容。

常见问题

模型配置错误

症状：Agent 在响应第一条消息时报错，日志中有 API 认证错误。

诊断：

# 检查 Gateway 日志中的模型错误
grep -i "error\|apikey\|unauthorized" logs/gateway.log | tail -20

解决：

  1. 验证 config.yaml 中 API key 字段名称正确（例如 $OPENAI_API_KEY）。
  2. 确认对应的环境变量已设置（echo $OPENAI_API_KEY）。
  3. 检查 base_url（如有）是否与提供商的实际端点匹配。

沙箱权限问题

症状：工具报”文件未找到”或权限错误，即使 Agent 声称已创建文件。

诊断：

# 检查线程用户数据目录是否存在且可写
ls -la backend/.facetx/threads/

解决：

  1. 确保 backend/.facetx/ 对运行 FacetX 的进程可写。
  2. 在 Docker 部署中，验证卷挂载路径正确（.facetx 设置为绝对路径）。
  3. 如果使用基于容器的沙箱，确认 Docker 已运行并且容器镜像已拉取。

SQLite 报 database is locked

症状：Docker 或团队部署中，多个用户同时使用时出现 sqlite3.OperationalError: database is locked。

原因：SQLite 支持并发读取，但同一时间只有一个写入者。FacetX 的检查点写入和应用写入会共享同一个 SQLite 数据库文件，多用户并发时可能竞争文件锁。

解决：生产环境或多用户部署切换到 Postgres：

database:
  backend: postgres
  postgres_url: $DATABASE_URL
 
run_events:
  backend: db

SQLite 应只用于本地开发、单用户部署或短期评估环境。

前端构建失败

症状：make install 或前端构建步骤失败，提示 BETTER_AUTH_SECRET 错误。

解决：

# 选项 1：设置环境变量（推荐）
export BETTER_AUTH_SECRET=your-secret-here-at-least-32-chars
cd frontend && pnpm build
 
# 选项 2：跳过构建时验证（仅限开发）
SKIP_ENV_VALIDATION=1 pnpm build

MCP 服务器连接失败

症状：MCP 工具未出现，logs/gateway.log 中有超时错误。

诊断：

# 检查 MCP 相关错误
grep -i "mcp\|timeout" logs/gateway.log | tail -20

解决：

  1. 验证 extensions_config.json 中 MCP 服务器的 command 和 args 在服务器外部正常工作（手动运行命令）。
  2. 确认 MCP 服务器的依赖（如 npx、uvx）已安装并在 PATH 中。
  3. 检查 MCP 服务器是否需要网络访问或特定环境变量。

K8s Provisioner 连接失败

症状：沙箱工具请求挂起，日志中有连接拒绝错误。

解决：

  1. 验证 config.yaml 中 provisioner_url 正确且 Provisioner Pod 运行正常。
  2. 检查 K8S_NAMESPACE 和 RBAC 配置是否允许 Provisioner 创建 Pod。
  3. 验证 SANDBOX_IMAGE 可以从 K8s 节点拉取。

数据备份

根据你启用的存储后端备份：

  • backend/.facetx/threads/：线程工作目录、上传文件和产出物。
  • backend/.facetx/memory.json 和 backend/.facetx/agents/：全局和 Agent 记忆。
  • ${database.sqlite_dir}/facetx.db：当使用 database.backend: sqlite 时备份，默认路径为 .facetx/data/facetx.db。
  • Postgres 数据库备份：当使用 database.backend: postgres 时定期导出。
  • 旧的 checkpointer.connection_string 文件：如果你的部署仍配置独立 checkpointer。
  • backend/agents/*/config.yaml：自定义 Agent 配置。

Docker 部署中，备份绑定挂载的宿主机路径，而不是容器内部文件系统。

停止和重启服务

# 停止所有本地服务
make stop
 
# 重启（停止后重新启动）
make stop && make dev

在 Docker 中：

docker compose -f docker/docker-compose-dev.yaml down
docker compose -f docker/docker-compose-dev.yaml up
部署指南配置
简介