### 背景与目标

本目录 `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/domains/chat/api/`，数据全部落在本地数据库
- 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. 启动服务

```bash
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`，开启本地模式并指向本地后端：

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

- 启动前端应用：

```bash
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`）

### 常用命令

```bash
# 查看运行中的容器
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）：

```bash
# 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 相关（仅开发者使用）

```bash
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 地址。