require api auth token

API图片修改-Agent.md

@@ -7,7 +7,35 @@
 - 本机：`http://localhost:3002`
 - 局域网：`http://192.168.31.204:3002`
 
-## 认证与 API Key
+## 必须携带 API 访问密钥
+
+所有受保护接口都需要 API 访问密钥。这个密钥不是 Gemini API Key，而是本服务自己的调用密钥，用来防止局域网内其他人随意调用你的接口。
+
+在服务端 `.env.local` 中配置：
+
+```env
+API_AUTH_TOKEN="YOUR_LONG_RANDOM_API_TOKEN"
+```
+
+调用时二选一携带：
+
+```txt
+Authorization: Bearer YOUR_LONG_RANDOM_API_TOKEN
+```
+
+或：
+
+```txt
+x-api-key: YOUR_LONG_RANDOM_API_TOKEN
+```
+
+如果没有配置 `API_AUTH_TOKEN`，`/api/generate`、`/api/edit-image`、`/api/analyze-document`、`/api/config/*` 等接口会拒绝请求。只在本机临时开发时，才可以设置：
+
+```env
+API_AUTH_DISABLED="true"
+```
+
+## Gemini API Key
 
 Gemini API Key 有三种传入方式，按优先级从高到低：
 
@@ -15,28 +43,17 @@ Gemini API Key 有三种传入方式，按优先级从高到低：
 2. 单次请求 JSON/Form 字段：`apiKey=YOUR_GEMINI_API_KEY`
 3. 服务端环境变量：`.env.local` 中的 `GEMINI_API_KEY`
 
-运行中更新服务端 Key：
+运行中更新服务端 Gemini Key：
 
 ```bash
 curl -X POST http://localhost:3002/api/config/api-key \
   -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_LONG_RANDOM_API_TOKEN" \
   -d "{\"apiKey\":\"YOUR_GEMINI_API_KEY\",\"persist\":true}"
 ```
 
 `persist:true` 会写入本项目的 `.env.local`，该文件不会提交到 git。
 
-如果服务设置了 `API_AUTH_TOKEN`，还需要在每次请求中加入：
-
-```txt
-Authorization: Bearer YOUR_API_AUTH_TOKEN
-```
-
-或：
-
-```txt
-x-api-key: YOUR_API_AUTH_TOKEN
-```
-
 ## 健康检查
 
 ```bash
@@ -50,7 +67,8 @@ curl http://localhost:3002/api/health
   "ok": true,
   "apiPort": 3002,
   "hasGeminiApiKey": true,
-  "authEnabled": false,
+  "authEnabled": true,
+  "authRequired": true,
   "acceptsPerRequestApiKey": true
 }
 ```
@@ -61,6 +79,7 @@ curl http://localhost:3002/api/health
 
 ```bash
 curl -X POST http://localhost:3002/api/edit-image \
+  -H "Authorization: Bearer YOUR_LONG_RANDOM_API_TOKEN" \
   -H "x-gemini-api-key: YOUR_GEMINI_API_KEY" \
   -F "prompt=保留主体不变，把背景改成干净的白色摄影棚，增强产品质感" \
   -F "imageSize=1K" \
@@ -108,6 +127,7 @@ curl -X POST http://localhost:3002/api/edit-image \
 ```bash
 curl -X POST http://localhost:3002/api/generate \
   -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_LONG_RANDOM_API_TOKEN" \
   -H "x-gemini-api-key: YOUR_GEMINI_API_KEY" \
   -d "{
     \"prompt\":\"把这张图改成赛博朋克夜景风格，但保留人物脸部特征\",
@@ -154,6 +174,7 @@ curl -X POST http://localhost:3002/api/generate \
 
 ```bash
 curl -X POST http://localhost:3002/api/analyze-document \
+  -H "Authorization: Bearer YOUR_LONG_RANDOM_API_TOKEN" \
   -H "x-gemini-api-key: YOUR_GEMINI_API_KEY" \
   -F "prompt=用中文总结这份文档，提取关键结论和待办事项" \
   -F "files=@report.pdf"
@@ -176,6 +197,7 @@ curl -X POST http://localhost:3002/api/analyze-document \
 
 ```bash
 curl -X POST http://localhost:3002/api/edit-image \
+  -H "Authorization: Bearer YOUR_LONG_RANDOM_API_TOKEN" \
   -H "x-gemini-api-key: YOUR_GEMINI_API_KEY" \
   -F "prompt=参考第二张图的色调，修改第一张图" \
   -F "files=@source.png" \
@@ -195,14 +217,17 @@ curl -X POST http://localhost:3002/api/edit-image \
 
 常见错误：
 
+- `Unauthorized. Send Authorization: Bearer YOUR_API_AUTH_TOKEN or x-api-key.`：缺少 API 访问密钥
+- `API_AUTH_TOKEN is required.`：服务端没有配置 API 访问密钥
 - `prompt or instruction is required.`：缺少修改指令
 - `Gemini API key is required.`：没有配置或传入 Gemini API Key
 - `Remote file is too large.`：URL 文件超过大小限制
 
 ## Agent 调用建议
 
-1. 优先使用 `POST /api/edit-image` + multipart 上传真实图片文件。
-2. 如果图片已经是 base64，使用 `POST /api/generate` 的 `images[].base64`。
-3. 每次调用都带 `x-gemini-api-key`，可避免依赖服务端环境。
-4. 取返回的 `images[0].dataUrl` 给用户预览；保存文件时解码 `images[0].data`。
-5. 修改指令尽量包含保留内容、需要改变的内容、输出用途和画幅比例。
+1. 每次调用都必须带 `Authorization: Bearer YOUR_LONG_RANDOM_API_TOKEN` 或 `x-api-key`。
+2. Gemini Key 建议用 `x-gemini-api-key` 单次传入，避免依赖服务端环境。
+3. 优先使用 `POST /api/edit-image` + multipart 上传真实图片文件。
+4. 如果图片已经是 base64，使用 `POST /api/generate` 的 `images[].base64`。
+5. 取返回的 `images[0].dataUrl` 给用户预览；保存文件时解码 `images[0].data`。
+6. 修改指令尽量包含保留内容、需要改变的内容、输出用途和画幅比例。