eigent/server/README_CN.md

背景与目标

本目录 server/ 是在客户端本地下放的后端服务（FastAPI + PostgreSQL）。目标：实现本地与云端完全数据分离。部署该服务后，用户的注册信息、模型提供商配置、工具配置、聊天历史等敏感数据均保存在本机的数据库中，不会上传到我们的云端，除非你主动配置了外部服务（如云端模型提供商或远程 MCP 服务器）。

本地下放的服务范围（主要模块）

• 用户与账号
  • POST /register：邮箱 + 密码注册（仅本地 DB）
  • POST /login：邮箱 + 密码登录，返回本地签发的 Token
  • GET/PUT /user、/user/profile、/user/privacy、/user/current_credits、/user/stat 等
• 模型提供商 Provider（保存你的模型访问配置）
  • GET /providers、POST /provider、PUT /provider/{id}、DELETE /provider/{id}
  • POST /provider/prefer：设置首选 Provider（前端与后端将优先使用）
• 配置中心 Config（保存各类工具/能力所需的密钥或参数）
  • GET /configs、POST /configs、PUT /configs/{id}、DELETE /configs/{id}、GET /config/info
• 聊天与数据
  • 历史、快照、分享等接口位于 app/controller/chat/，数据全部落在本地数据库
• MCP 服务管理（导入本地/远程 MCP 服务器）
  • GET /mcps、POST /mcp/install、POST /mcp/import/{Local|Remote} 等

说明：上述数据均保存在 Docker 中的本地 PostgreSQL 卷中（见“数据持久化”），不经我们云端。若你配置了外部模型或远程 MCP，则相应请求会发往你指定的第三方服务。

---

快速开始（Docker 推荐）

前置要求

• Docker Desktop：已安装并运行
• Python：3.10.*（推荐使用 3.10.15）
• Node.js：>=18.0.0 <23.0.0

Triggers 托管配置

重要提示：如果你计划使用 应用触发器（外部 Webhook 回调），你必须使用公开可访问的域名来托管此服务器。应用触发器需要外部服务能够通过 HTTPS 回调 URL 访问你的服务器。

• 本地开发时，可以使用 ngrok 等工具暴露你的本地服务器
• 生产环境请使用正式域名并配置 SSL 证书

启动步骤

1. 启动服务

cd server
# 复制 .env.example 为 .env(或者按照.env.example的格式创建.env)
cp .env.example .env
# .env 中的环境变量会自动传递给 Docker 镜像
docker-compose up --build -d

注意：

• 数据库迁移由 Alembic 在容器启动时自动执行
• .env 中定义的所有环境变量都会自动传递给 Docker 镜像

2. 启动前端（本地模式）

• 在项目根目录创建或修改 .env.development，开启本地模式并指向本地后端：

VITE_BASE_URL=/api
VITE_USE_LOCAL_PROXY=true
VITE_PROXY_URL=http://localhost:3001

• 启动前端应用：

npm install
npm run dev

访问 API 文档

• 浏览器打开 http://localhost:3001/docs（Swagger UI）

容器与端口

• API 服务：本机 3001 → 容器 5678
• PostgreSQL：本机 5432 → 容器 5432

数据持久化

• 数据库数据存放在 Docker 卷 server_postgres_data，容器路径 /var/lib/postgresql/data
• 容器启动时会自动执行数据库迁移（见 start.sh 中的 alembic upgrade head）

常用命令

# 查看运行中的容器
docker ps

# 停止/启动 API 容器（保留数据库）
docker stop eigent_api
docker start eigent_api

# 停止/启动全部（API + DB）
docker compose stop
docker compose start

# 查看日志
docker logs -f eigent_api | cat
docker logs -f eigent_postgres | cat

提示：若拉取镜像缓慢，可在 Docker Desktop 配置国内镜像加速后重试。

---

开发模式（可选）

如果希望在本地以热重载方式开发 API（数据库仍用 Docker 中的 Postgres）：

# 1) 停止容器中的 API 服务，仅保留数据库
 docker stop eigent_api

# 2) 初始化数据库（首次或数据库结构变更时）
 cd server
 uv run alembic upgrade head

# 3) 本地启动（需提供数据库连接串）
 # 方式 A：在当前 shell 导出环境变量
 export database_url=postgresql://postgres:123456@localhost:5432/eigent
 uv run uvicorn main:api --reload --port 3001 --host 0.0.0.0

 # 方式 B：在 server/.env 中写入（示例）
 # database_url=postgresql://postgres:123456@localhost:5432/eigent
 # 然后直接运行同样的 uvicorn 命令
uv run uvicorn main:api --reload --port 3001 --host 0.0.0.0

---

其它

• API 文档：http://localhost:3001/docs
• 运行时日志：容器内 /app/runtime/log/app.log
• i18n 相关（仅开发者使用）

uv run pybabel extract -F babel.cfg -o messages.pot .
uv run pybabel init -i messages.pot -d lang -l zh_CN
uv run pybabel compile -d lang -l zh_CN

如需完全离线环境，请仅使用本地模型与本地 MCP 服务器，并避免配置任何外部 Provider 与远程 MCP 地址。