内容
服务器
> 用于图像生成的 MCP 服务器-IP 铸造工作> 支持多个 AI（Google Gemini、Openplicate、St），默认 Gemini
---
目录
-开始](#-快速开始 - [安装依赖安装依赖)
配置环境变量](#配置环境变量)
- [启动服务](#3-启动服务)
- [API 文档](#-api-文档)
- [会话管理](#1-会话管理)
生成](#2-图像生成)
- [确认和暂存](#3-确认和暂存)
[管理员 API](#4-api)
- [支持的 AI 提供商](#-支持的-ai-提供商和模型)
- [Google Gemini（默认）](#google-gemini默认)
- [OpenAI DALL-E](#openai-dall-e)
- [Replicate](#replicate)
- [Stability AI](#)
- [完整工作流示例](#工作流示例)
环境变量配置](#-配置)
- [-数据库- [测试](#-测试)
- [生产部署生产部署指南错误处理](#处理)
---
## 快速开始
###. 安装依赖
``` install
```
. 配置环境 `.env` 文件并填写您的 API 密钥：bash
# 默认可选，默认为）
AI_PROVIDER=
# Google Gemini（商）
GEMINI=您的 Gemini API 密钥
# 可选：如果不设置，则使用代码默认ini-3-proGEMINI_MODEL=gemini-3-pro
# OpenAI DOPENAI_API您的 OpenAI 密钥plicate
RE=您的 Re令牌
# Stability AI
STABILITY_API_KEY=您的 Stability AI 密钥
```
### 3. 启动服务
```bash
# 开发模式（热重载）
npm run dev
# 生产模式
npm run build && npm start
```
服务默认在 `http://localhost:3000` 上运行
---
## 📖 API 文档
### 基础 URL
```
http://localhost:3000/api
```
---
### 1. 会话管理
会话不需要手动创建。当调用 `/api/generate` 时：
- 如果没有 `session_id`：服务会自动创建一个新的会话，并在响应中返回 `session_id`
- 如果有 `session_id`：在同一个会话中继续生成/迭代（Gemini 支持多轮上下文）
目前，没有公开的 HTTP 端点用于检索会话信息或历史记录。
### 2. 图像生成
#### 生成图像
```bash
POST /api/generate
Content-Type: application/json
{
"prompt": "一只美丽的猫在花园里",
"provider": "gemini",
"model": "gemini-3-pro-image-preview",
"negative_prompt": "模糊的，低质量的",
"aspect_ratio": "16:9"
}
```
**参数描述：**
| 参数 | 是否必填 | 描述 |
|:----------|:--------:|:------------|
| `session_id` | ❌ | 可选，会话 ID；如果不提供，则自动创建 |
| `prompt` | ✅ | 生成提示 |
| `provider` | ❌ | AI 提供商：`gemini`（默认）/ `openai` / `replicate` / `stability` |
| `model` | ❌ | 模型名称（参见下面的支持模型列表） |
| `negative_prompt` | ❌ | 负面提示（要排除的内容） |
| `aspect_ratio` | ❌ | 宽高比：`1:1` / `16:9` / `9:16` 等 |
**响应示例：**
```json
{
"image_url": "http://localhost:3000/temp/gen_xyz789.png",
"generation_id": "gen_xyz789",
"prompt": "一只美丽的猫在花园里",
"provider": "gemini",
"model": "gemini-3-pro-image-preview",
"session_id": "sess_abc123",
"is_new_session": true,
"created_at": 1701504500000
}
```
`generation_id` 是用于确认图像并将其移动到暂存区的标识。
#### 查询可用提供商（当前未公开）
此 HTTP 端点当前已禁用；该功能在代码中保留（`src/routes/generate.ts`），取消注释即可启用。
### 3. 确认和暂存
确认生成的图像并上传到 ICP 链上存储，为 Gen-IP 铸造做准备：
```bash
POST /api/session/confirm
Content-Type: application/json
{
"session_id": "sess_abc123",
"generation_id": "gen_xyz789",
"name": "",
"description": "一只猫在花园里"
}
```
**响应示例：**
```json
{
"id": "stg_abc123",
"name": "我的美丽的猫",
"description": "一只猫在花园里",
"image_url": "https://wgfis-kyaaa-aaaan-q2c3a-cai.raw.icp0.io/images/abc123xyz.png",
"prompt": "一只美丽的猫在花园里",
"from": "ChatGPT",
"created_at": 1701504500000,
"expires_at": 1701590900000,
"status": "pending"
}
```
> **注意：**
> - 图像上传到链上容器存储，`image_url` 返回一个链上可访问的 URL。如果 ICP 服务不可用，则回落到本地存储。
> - `from` 字段标识调用源：`ChatGPT`（HTTPS API 调用）或 `Claude`（MCP 工具调用）。
#### 预览暂存图像
确认后，图像因存储方式而异：
| 存储 URL 格式 |
|:---------------|:-----------|
| **ICP 链上存储**（默认） |://{canister_id}.raw.icp0.io/images/{file_id}.png` |
| ****（备用 `http://localhost0/uploads/{stagingpng` |
暂存状态
GET /api?id=:staging_id
```
---
### 管理员 API
管理员 API 用于系统管理和配置 `ADMIN_API 才能使用。
认证方式
在请求头中添加 `x-api-key`：
```bash
curl -H "x-api-key: your-admin-key"localhost:3000/api/admin/xxx#### 获取系统统计```bash
api/admin/stats
```
**响应**
```json
"active_s 5,
"total_generations42,
"staging_total": 10 "staging_pending": 7,
"staging_minted": 3```
#### 列出所有
```bash
GET /api/admin/sessions
```
**响应示例json
{
sessions": [
"id": "123",
created_at": 1700,
expires_at": 1701507600000,
"generation_count": 3
}
]
}
```
#### 列出所有暂存图像
```bash
GET /api/admin/staging
```
**响应示例：**
```json
{
"items": [
{
"id": "stg_xyz789",
"name": "我的 Gen-IP",
"status": "pending",
"image_url": "http://localhost:3000/uploads/stg_xyz789.png",
"created_at": 1701504500000
}
]
}
```
#### 删除暂存图像bash
DELETE/staging_id
响应示例：
{
": true
}
触发手动清理期的会话、暂存图像```bash
/admin/cleanup**响应示例：json
{
_sessions": "clean": "cleaned_st 1
}
注意事项
| |
|:-----|
| | 使用**恒**以防止时间攻击 |
| 未配置管理员端点` 错误 |
密钥 | 返回 `401 Unauthorized` |
🤖 支持的和模型
和默认值集中在 `src/config/models.ts，可以通过环境变量覆盖GEMINI_MODELOPENAI `REPLICATE / `STABILITY 或通用 `AI。
### Google）
```# 使用 Gemini 默认gemini-3）
curl POST http://localhost/api/generateH "Content/json" \
d '{
": " "prompt":",
"gemini"
# 指定 Imagen 模型
curl http://localhost:3000/api/g -H " application/json"d '{
session_id": "prompt猫",
": "gemini",
"model": ".0-002"
**支持的| 模型 ||:------|:| `gemini-3-pro-image-preview` | Nano Banana Pro，最模型（默认） |
| `gemini.5-flash-image` | Nano Banana图像生成模型 |
| `gemini-2.0-flash-exp` | 旧的实验模型 |
> 任何支持图像生成的 Gemini/Imagen 模型也可以传递（例如 `imagen-3.0-generate-002`）。
### OpenAI DALL-E
```# 使用 DALL-E-3（curl -Xlocalhost:3000/api/generate \
-H "Content-Type" \
{
_id": "xxx "prompt": " "provider": "openai",
": "d3"
# 使用 D2（较 -X POST:3000 \
Content-Type: \
- "sessionxxx",
": "一只 "provider":ai",
"dall"
}支持的模型| 模型 | 价格 |
|:|:------|
all-e | 最新模型，质量最佳 | $0.04-0.12/图像 |
| `dall-e-2`模型，较便宜 | $0.016-0.02/图像 |
> 图像编辑端点默认为 `gpt-image-1`（可通过 `model` 覆盖，支持 `gpt-image-1` / `dall-e-2`）。
### Replicate
```bash
# 使用 Flux Schnell，推荐）
curl -X POST http://localhost:3000/api/generate \
-H "Content-Type: application/json" \
-d '{
"session_id": "xxx",
"prompt": "一只猫",
"provider": "replicate",
"model": "black-forest-labs/flux-schnell"
}'
# 使用 SDXL
curl -X POST http://localhost:3000/api/generate \
-H "Content-Type: application/json" \
-d '{
"session_id": "xxx",
"prompt": "一只猫",
"provider": "replicate",
"model": "stability-ai/sdxl"
}'
```
**支持的模型：**
| 模型 | 描述 |
|:------|:------------|
| `black-forest-labs/flux-schnell` | 快速且免费（推荐） |
| `black-forest-labs/flux-dev` | 高质量开发版本 |
| `black-forest-labs/flux-pro` | 专业版本，最高质量 |
| `stability-ai/s` | 稳定扩散 XL |
| `stability-ai/stable-diffusion-3` | SD3 最新版本 |
| `bytedance/sdxl-lightning-4step` | 快速生成 |
| `lucatacol-lcm` | LCM 快速生成 |
| `playgroundai/playground-v2.102-aesthetic` | 风格 |
> 您也可以传递 Replicate 模型 ID；上述是项目内置推荐（参见 `src/config/models.ts`）。
### Stability AI
```bash
# 使用 Stability AI -X POST http://localhost:3000/api/generate \
-H "Content-Type: application/json" \
-d '{
": "xxx",
"prompt": "一只猫",
"provider": "stability'
```
**支持的宽高比：**
`16:9` · `1:1` · `21:9` · `2:3` · `3:2` · `4:5` · `5:4` · `9:16` · `9:21`
---
## 📋 完整工作流示例
### 命令行快速测试（生产环境）
```bash
# 生产环境基准 URL
BASE_URL="https://vly-money-mcp-service.zkid.xyz"
# 健康检查
curl $BASE_URL/health
# 使用 Google Gemini（默认）；如果不提供 session_id，则自动创建会话
curl -X POST $BASE_URL/api/generate \
-H "Content-Type: application/json" \
-d '{"prompt": "一只猫", "provider": "gemini"}'
# 使用 OpenAI DALL-E-3
curl -X POST $BASE_URL/api/generate \
-H "Content-Type: application/json" \
-d '{"prompt": "一只猫", "provider": "openai", "model": "dall-e'
# 使用 Replicate Flux
curl -X POST $BASE_URL/api/generate \
-H "Content-Type: application/json" \
-d '{"prompt": "一只猫", "provider": "replicate", "model": "black-forest-labs/flux-schnell"}'
# 使用 Stability AI
curl -X POST $BASE_URLenerate \
-H "Content-Type: application/json" \
-d '{"prompt": "一只猫", "provider": "stability"}'
# 确认图像并移动到暂存区（需要从 generate 端点响应中获取 generation_id）
curl -X POST $BASE_URL/api/session/confirm \
-H "Content-Type: application/json" \
-d '{"session_id": "your_session_id", "generation_id": "your_generation_id", "name": "我的猫图像", "description": "爱的猫"} 完整 Shell 脚本示例
```bash
# 生成图像（如果 session_id，则自动创建会话）
RESULT=$(curl -s -X POST http://localhost:3000/api/generate \
-H "Content-Type: application/json" \
-d "{
\"prompt\": \"一只美丽的日落景色\",
\"provider\": \"gemini\",
\"aspect_ratio\": \"16:9\"
}")
SESSION=$(echo $RESULT | jq -r '.session_id')
IMAGE_URL=$(echo $RESULT | jq -r '.image_url')
GEN_ID=$(echo $RESULT | jq -r '.generation_id')
echo "会话：$SESSION "图像 URL：$IMAGE_URL"
echo "生成 ID：$"
# 2. 预（在浏览器中打开）
IMAGE_URL"
# 3. 确认并暂存
STAGING=$(curl -s -X POST "http://localhost:3000/api/session/confirm" \
-H "Content-Type: application/json" \
-d "{
\"session_id\": \"$SESSION\",
\"generation_id\": \"$GEN_ID\",
\"name\": \"日落景色\",
\"description\": \"美丽的日落景色\"
}")
STAGING_ID=$(echo $STAGING | jq -id')
STAGING_URL $STAGING | jq '.image_url')
echo "暂存 ID：$STAGING_ID"
echo "暂存 URL：$STAGING_URL"
# 4. 检查暂存状态
curl -s "http://localhost:3000/api/staging?id=$STAGING_ID" |```
---
## 图像访问路径 阶段 | 存储 路径格式 | 描述 |
|:------|:-----------------|:------------|:------------|
| 生成中 | 本地临时存储 | `http://localhost:3000/temp/{generation_id}.png` | ，会话过期后| 已确认ICP 链上 | `httpscanister_id}.p0.iofile_id}.png 永久链 |
| 已备用） | 本 `http:3000/uploads_id}.png` | ICP 不可用时的本地存储 |
### ICP 链上存储概述
默认使用 **Internet Computer）**图像存储： **去中心**：图像存储 区块链上，具有高可用性和耐用- **分**：支持大段上传，每个默认为 500- **HTTP 网关访问**：图像 `raw.icp` 域名直接访问，无需额外代理
- **自动备用**：如果 ICP 服务不可用，则自动回落到本地存储
配置 ICP 存储（`.env`）：
```bash
ICP_ENABLED=true # 启用 ICP 存储
ICP_HOST=https://ic0.app # ICP 主ICP_ASSETS_CANISTER_IDis-kyaaa-aa2c3a-c # 您的容器 ID
UNK_SIZE=512000 # 分段大小（默认 500KB）
```
---
## ⚙变量配置
```bash
# ============================================================
# 服务器配置
# ============================================================
PORT=3000
NODE_ENV=development
BASE_URL=http://localhost:3000
# ============================================================
# 存储配置
# ============================================================
UPLOAD_DIR=./uploads
TEMP_DIR=./temp
# ============================================================
# TTL 配置
# ============================================================
SESSION_TTL_HOURS=50 # 会话有效期
STAGING_TTL=24 #存有效期
# ============================================================
# 限制配置
#PROMPT_MAX_LENGTH # 最大提示长度_GENERATIONS_PER_MIN # 每分钟全局生成
SESSION_GENERATION_LIMIT # 每会话生成次数FILE_SIZE_LIMIT=104 # 文件大小限制（）
# ============================================================
提供商配置
# =================================================_PROVIDER=gemini 提供商
# Google Gemini）
GEMINI_API_KEY=您的 Gemini API 密钥
#：如果不设置，则使用模型（gemini-3-preview）
GEMINI_MODELini-3-pro-image-preview OpenAI
OPENAI=sk-xxx
OPENAI_MODEL=dall-e-3 Replicate
REPLICATE_APIxxx
REPLICATE_MODEL-forest-labs/flux-schnell
# Stability AIABILITY_API_KEY=sk-# ============================================================
# 管理
# ============================================================
ADMIN_API_KEY=您的密钥
# =================================================链上存储# ============================================================
ICP_ENABLED=true # 启用 ICP 存储（）
ICP_HOST=https://ic0 # ICP 网络主机主网）
ICP_ASSETS_CANISTER_ID=wgfis-k-aaaan-q2c-cai # 容器 ID
ICP_CHUNK512000 # 分（默认 500KB）
# ============================================================
# SQLite
# ============================================================
DB_PATH=./data/mcp.db # 数据库文件路径
DB_WAL_MODE # 启用 WAL（提高并发性能）
_MEMORY=false # 使用内存用于测试）
```
---
## 数据库概述
该项目使用 **SQLite** 作为数据存储，通过 `better-sqlite3`高性能同步操作。
### 数据库功能
| 功能 | 描述 |
|:--------|:------------|
| ** 模式** | -Ahead Logging并发读取不会阻塞读取 **预编译语句** | SQL 语句预编译解析开销 |
| **化** | 数据自动，无需手动保存 |
| **事务支持** | 批量操作使用事务，确保数据一致性 |
| **外键约束**启用外键约束，自动级联删除相关数据 |
### 数据库表结构
```
sessions # 用户会话
├── id # 会话 ID
├── created_at # 创建时间
└── expires_at # 过期时间
generations # 图片生成记录
├── id # 生成 ID
├── session_id # 关联会话（外键）
├── prompt # 提示信息
├── image_url # 图片 URL
└── ...
staging # Gen-IP 中转记录
├── id # 中转 ID
├── name # Gen-IP 名称
├── status # 状态（待处理/已完成）
└── ...
```
### 性能优化
- **索引优化**：在 `expires_at`、`session_id`、`status` 等频繁查询字段上创建索引
- **批量操作**：使用事务进行批量插入/更新，减少磁盘 I/O
- **连接复用**：单例数据库连接，避免重复创建连接开销
### 数据库维护
```bash
# 查看数据库大小
ls -lh ./data/mcp.db
# 优化数据库文件（回收空间）
sqlite3 ./data/mcp.db "VACUUM"
# 查看表结构
sqlite3 ./data/mcp.db ".schema"
# 查看数据统计
sqlite3 ./data/mcp.db "SELECT COUNT(*) FROM sessions; SELECT COUNT(*) FROM staging;"
```
---
## 🧪 测试
本项目使用 **Vitest** 作为测试框架，提供全面的单元测试和集成测试。
### 运行测试
```bash
# 运行所有测试
npm test
# 监听模式（开发过程中推荐）
npm run test:watch
# 生成覆盖率报告
npm run test:coverage
# 可视化测试界面
npm run test:ui
```
### 测试覆盖率
| 模块 | 测试文件 | 测试数量 | 描述 |
|:-------|:----------|:----------:|:------------|
| 工具类 | `tests/unit/utils/*.test.ts` | 55 | ID 生成、错误处理、图片尺寸计算 |
| 中间件 | `tests/unit/middleware/*.test.ts` | 25 | 限流、管理员 API 身份验证、每日限流 |
| 数据库 | `tests/unit/db/index.test.ts` | 46 | 会话/生成/中转 CRUD、事务、索引 |
| API 路由 | `tests/unit/routes/*.test.ts` | 49 | 会话、中转、管理员、生成、编辑 API 测试 |
| AI 服务 | `tests/unit/services/*.test.ts` | 30 | AI 提供商、Gemini 限流器 |
**总计：205 个测试**
### 测试文件结构
```
tests/
├── unit/
│ ├── utils/
│ │ ├── id.test.ts # ID 生成函数测试
│ │ ├── errors.test.ts # 错误类和工具函数测试
│ │ └── image.test.ts # 图片尺寸计算测试
│ ├── middleware/
│ │ ├── auth.test.ts # 管理员 API 身份验证测试
│ │ ├── rateLimit.test.ts # 限流测试
│ │ └── dailyRateLimit.test.ts # 每日限流测试
│ ├── db/
│ │ └── index.test.ts # SQLite 数据库操作测试
│ ├── routes/
│ │ ├── session.test.ts # 会话 API 测试
│ │ ├── staging.test.ts # 中转 API 测试
│ │ ├── admin.test.ts # 管理员 API 测试
│ │ ├── generate.test.ts # 生成 API 测试
│ │ └── edit.test.ts # 编辑 API 测试
│ └── services/
│ ├── ai.test.ts # AI 提供商测试
│ ├── gemini-rate-limiter.test.ts # Gemini 限流器测试
│ └── gemini-provider.test.ts # Gemini 提供商测试
├── fixtures/
│ └── mocks.ts # 模拟数据和辅助函数
└── setup.ts # 测试配置和初始化
```
### 测试配置
测试配置位于 `vitest.config.ts`:
| 配置项 | 值 |
|:------------|:------|
| 环境 | Node.js |
| 隔离 | 每个测试文件独立运行 |
| 并行 | 使用 forks 多进程池（避免原生模块冲突） |
| 超时 | 10 秒 |
| 数据库 | 测试期间使用 SQLite 内存模式 |
### 编写新测试
```typescript
import { describe, it, expect, beforeEach, vi } from 'vitest';
describe('功能模块', () => {
beforeEach(() => {
// 测试前设置
});
it('应正确执行某些功能', () => {
// 测试代码
expect(result).toBe(expected);
});
});
```
---
## 🚢 生产部署指南
### 1. 要求
| 要求 | 最小值 |
|:------------|:--------|
| Node.js | >= 18.x |
| npm | >= 9.x |
| 磁盘空间 | 1GB+ |
| 内存 | 512MB+ |
### 2. 生产环境配置
复制 `.env.example` 并修改为生产环境：
```bash
cp .env.example .env
```
**必填配置更改：**
| 配置项 | 开发环境值 | 生产环境值 | 描述 |
|:------------|:------------------|:-----------------|:------------|
| `NODE_ENV` | `development` | `production` | **必须更改** |
| `BASE_URL` | `http://localhost:3000` | `https://your-domain.com` | **必须更改** |
| `ADMIN_API_KEY` | 空 | 强密码 | **必须设置** |
<details>
<summary><b>📄 完整的生产环境配置示例（点击展开）</b></summary>
```bash
# ============================================================
# 基本配置
# ============================================================
PORT=3000
NODE_ENV=production
BASE_URL=https://your-domain.com
# ============================================================
# 存储配置
# ============================================================
UPLOAD_DIR=./uploads
TEMP_DIR=./temp
# ============================================================
# TTL 配置（可为生产环境延长）
# ============================================================
SESSION_TTL_HOURS=50
STAGING_TTL_HOURS=72
# ============================================================
# 限流配置（根据服务器性能调整）
# ============================================================
PROMPT_MAX_LENGTH=400
GLOBAL_GENERATIONS_PER_MIN=30
SESSION_GENERATION_LIMIT=50
FILE_SIZE_LIMIT=10485760
# ============================================================
# AI 提供商（至少配置一个）
# ============================================================
AI_PROVIDER=gemini
# Google Gemini（默认）
GEMINI_API_KEY=your-production-gemini-key
# 可选：如果未设置，则使用代码默认模型（gemini-3-pro-image-preview）
GEMINI_MODEL=gemini-3-pro-image-preview
# OpenAI
OPENAI_API_KEY=sk-your-production-key
OPENAI_MODEL=dall-e-3
# Replicate
REPLICATE_API_TOKEN=your-production-token
REPLICATE_MODEL=black-forest-labs/flux-schnell
# Stability AI
STABILITY_API_KEY=sk-your-production-key
# ============================================================
# 安全配置（必须设置！）
# ============================================================
ADMIN_API_KEY=your-strong-secret-key-at-least-32-chars
# ============================================================
# SQLite 数据库配置
# ============================================================
DB_PATH=./data/mcp.db
DB_WAL_MODE=true
```
</details>
### 3. 部署方式
<details>
<summary><b>方式 1：直接部署</b></summary>
```bash
# 1. 克隆仓库
git clone https://github.com/your-repo/mcp_server.git
cd mcp_server
# 2. 安装生产环境依赖
npm install --production
# 3. 创建必要目录
mkdir -p uploads temp data
# 4. 设置目录权限
chmod 755 uploads temp data
# 5. 配置环境变量
cp .env.example .env
# 编辑 .env 文件，设置生产环境配置
# 6. 构建项目
npm run build
# 7. 启动服务
npm start
```
</details>
<details>
<summary><b>方式 2：使用 PM2（推荐）</b></summary>
PM2 是一个 Node.js 进程管理器，支持自动重启、负载均衡、日志管理等。
```bash
# 1. 全局安装 PM2
npm install -g pm2
# 2. 构建项目
npm run build
# 3. 使用 PM2 启动
pm2 start dist/index.js --name "mcp-server" --env production
# 4. 查看状态
pm2 status
# 5. 查看日志
pm2 logs mcp-server
# 6. 设置开机自启动
pm2 save
pm2 startup
```
**PM2 配置文件（可选）**
创建 `ecosystem.config.js`:
```javascript
module.exports = {
apps: [{
name: 'mcp-server',
script: 'dist/index.js',
instances: 1,
autorestart: true,
watch: false,
max_memory_restart: '1G',
env_production: {
NODE_ENV: 'production'
}
}]
};
```
使用配置文件启动：
```bash
pm2 start ecosystem.config.js --env production
```
</details>
<details>
<summary><b>方式 3：使用 Docker</b></summary>
**Dockerfile:**
```dockerfile
FROM node:18-alpine
WORKDIR /app
# 复制依赖文件
COPY package*.json ./
# 安装生产环境依赖
RUN npm install --production
# 复制源代码
COPY . .
# 构建
RUN npm run build
# 创建存储目录
RUN mkdir -p uploads temp data
# 暴露端口
EXPOSE 3000
# 启动命令
CMD ["node", "dist/index.js"]
```
**docker-compose.yml:**
```yaml
version: '3.8'
services:
mcp-server:
build: .
ports:
- "3000:3000"
volumes:
- ./uploads:/app/uploads
- ./temp:/app/temp
- ./data:/app/data
env_file:
- .env
restart: unless-stopped
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
interval: 30s
timeout: 10s
retries: 3
```
运行：
```bash
# 构建并启动
docker-compose up -d
# 查看日志
docker-compose logs -f
# 停止
docker-compose down
```
</details>
### 4. 反向代理配置
<details>
<summary><b>Nginx 配置</b></summary>
```nginx
server {
listen 80;
server_name your-domain.com;
# 重定向到 HTTPS
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl http2;
server_name your-domain.com;
# SSL 证书配置
ssl_certificate /path/to/fullchain.pem;
ssl_certificate_key /path/to/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
# 安全头部
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-XSS-Protection "1; mode=block" always;
# 上传文件大小限制
client_max_body_size 20M;
# 代理配置
location / {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_cache_bypass $http_upgrade;
proxy_read_timeout 300s;
}
# 静态资源缓存
location /uploads/ {
proxy_pass http://127.0.0.1:3000/uploads/;
proxy_cache_valid 200 7d;
add_header Cache-Control "public, max-age=604800";
}
location /temp/ {
proxy_pass http://127.0.0.1:3000/temp/;
proxy_cache_valid 200 1h;
add_header Cache-Control "public, max-age=3600";
}
}
```
</details>
<details>
<summary><b>Caddy 配置（更简单）</b></summary>
```caddyfile
your-domain.com {
reverse_proxy localhost:3000
# 静态资源缓存
@static path /uploads/* /temp/*
header @static Cache-Control "public, max-age=86400"
}
```
</details>
### 5. 健康检查与监控
```bash
# 检查服务是否运行
curl http://localhost:3000/health
# 预期响应
{"status":"ok","provider":"gemini","mcp_sessions":0}
# 获取系统统计信息（需要 ADMIN_API_KEY）
curl -H "x-api-key: your-admin-key" https://your-domain.com/api/admin/stats
```
### 6. 备份策略
```bash
# 方法 1：直接复制数据库文件（推荐在服务停止时进行）
cp ./data/mcp.db ./backup/mcp-$(date +%Y%m%d).db
# 方法 2：在线备份，使用 sqlite3 命令（在服务运行时安全）
sqlite3 ./data/mcp.db ".backup './backup/mcp-$(date +\%Y\%m\%d).db'"
# 方法 3：完整备份（包括图片文件）
tar -czf backup-$(date +%Y%m%d).tar.gz uploads data
```
**设置定时备份（crontab）：**
```bash
# 每天凌晨 2 点备份
0 2 * * * sqlite3 /app/data/mcp.db ".backup '/backup/mcp-$(date +\%Y\%m\%d).db'"
# 每周完整备份（包括图片）
0 3 * * 0 tar -czf /backup/mcp-full-$(date +\%Y\%m\%d).tar.gz /app/uploads /app/data
```
### 7. 安全检查清单
请在部署前验证：
- [ ] `NODE_ENV` 设置为 `production`
- [ ] `BASE_URL` 设置为正确的生产环境域名
- [ ] `ADMIN_API_KEY` 设置为足够的复杂度（推荐 32+ 字符）
- [ ] 所有 API Key 使用生产环境密钥
- [ ] HTTPS 已启用
- [ ] 反向代理已配置
- [ ] 限流参数设置适当
- [ ] 日志持久化已配置
- [ ] 定时备份已设置
- [ ] 健康检查端点已测试
### 8. 常见问题
| 问题 | 解决方案 |
|:------|:---------|
| 图片 URL 返回 localhost | 检查 `BASE_URL` 是否正确设置为生产环境域名 |
| 管理员 API 返回 500 错误 | 验证 `ADMIN_API_KEY` 环境变量是否设置 |
| 服务重启后数据丢失 | 验证 `data` 目录是否存在且有写权限 |
| 图片生成失败 | 检查 AI 提供商的 API Key 是否有效且账户余额充足 |
---
## ❌ 错误处理
API 返回标准 HTTP 状态码和 JSON 错误响应：
| 状态码 | 描述 |
|:-----------:|:------------|
| 400 | 请求参数错误 |
| 404 | 资源未找到（会话过期、中转未找到等） |
| 429 | 限流超过限制 |
| 500 | 内部服务器错误 |
**错误响应格式：
```json
{
"error": "会话过期或未找到",
"code": "SESSION_EXPIRED",
"details": {
"session_id": "sess_abc123"
}
}
```
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器