require api auth token

2026-05-09 17:39:18 +08:00
parent 57287cbc67
commit a23ce5b08f
4 changed files with 93 additions and 29 deletions
--- a/.env.example
+++ b/.env.example
@@ -14,9 +14,12 @@ APP_URL="MY_APP_URL"
 # API_PORT: HTTP API server port. Frontend still runs on 3000 by default.
 API_PORT="3002"

-# API_AUTH_TOKEN: Optional token for API calls. Leave empty to disable auth.
-# When set, send Authorization: Bearer <token> or x-api-key: <token>.
-API_AUTH_TOKEN=""
+# API_AUTH_TOKEN: Required token for protected API calls.
+# Send it as Authorization: Bearer <token> or x-api-key: <token>.
+API_AUTH_TOKEN="CHANGE_ME_TO_A_LONG_RANDOM_TOKEN"
+
+# API_AUTH_DISABLED: Only set this to true for local-only development.
+API_AUTH_DISABLED="false"

 # API callers can also send a temporary Gemini key per request with:
 # x-gemini-api-key: <Gemini API Key>
--- a/API图片修改-Agent.md
+++ b/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. 修改指令尽量包含保留内容、需要改变的内容、输出用途和画幅比例。
--- a/README.md
+++ b/README.md
@@ -23,17 +23,38 @@ View your app in AI Studio: https://ai.studio/apps/96002e3b-5eec-4566-85e8-71871

 The UI runs on port `3000`. The HTTP API runs separately on port `3002`.

-1. Set `GEMINI_API_KEY` in `.env.local` or your shell.
+1. Set `GEMINI_API_KEY` and `API_AUTH_TOKEN` in `.env.local` or your shell.
 2. Start the API:
   `npm run api`
 3. Check the API:
   `http://localhost:3002/api/health`

+Example `.env.local`:
+
+```env
+GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
+API_AUTH_TOKEN="YOUR_LONG_RANDOM_API_TOKEN"
+API_PORT="3002"
+```
+
+All protected API calls must send one of these headers:
+
+```txt
+Authorization: Bearer YOUR_LONG_RANDOM_API_TOKEN
+```
+
+or:
+
+```txt
+x-api-key: YOUR_LONG_RANDOM_API_TOKEN
+```
+
 You can change the server API key without restarting:

 ```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}"
 ```

@@ -42,6 +63,7 @@ You can also pass a temporary Gemini key for one call:
 ```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\":\"Create a clean product poster\"}"
 ```
@@ -53,6 +75,7 @@ Generate or edit with JSON/base64:
 ```bash
 curl -X POST http://localhost:3002/api/generate \
  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_LONG_RANDOM_API_TOKEN" \
  -d "{\"prompt\":\"Create a clean product poster for a white coffee mug\",\"imageSize\":\"1K\",\"aspectRatio\":\"1:1\"}"
 ```

@@ -60,6 +83,7 @@ Upload an image or document with a prompt:

 ```bash
 curl -X POST http://localhost:3002/api/generate/upload \
+  -H "Authorization: Bearer YOUR_LONG_RANDOM_API_TOKEN" \
  -F "prompt=Change the background to a bright studio scene" \
  -F "imageSize=1K" \
  -F "aspectRatio=1:1" \
@@ -70,10 +94,11 @@ Analyze a document:

 ```bash
 curl -X POST http://localhost:3002/api/analyze-document \
+  -H "Authorization: Bearer YOUR_LONG_RANDOM_API_TOKEN" \
  -F "prompt=Summarize this document in Chinese" \
  -F "files=@report.pdf"
 ```

-Optional API auth: set `API_AUTH_TOKEN`, then send either `Authorization: Bearer <token>` or `x-api-key: <token>`.
+API auth is required by default. For local-only development, you can set `API_AUTH_DISABLED=true`, but do not use that on a LAN or server.

 For Agent-facing image editing instructions, see `API图片修改-Agent.md`.
--- a/server/index.ts
+++ b/server/index.ts
@@ -51,6 +51,7 @@ const apiPort = Number(process.env.API_PORT || 3002);
 const defaultImageModel = process.env.GEMINI_IMAGE_MODEL || 'gemini-3.1-flash-image-preview';
 const defaultTextModel = process.env.GEMINI_TEXT_MODEL || 'gemini-2.5-flash';
 const apiAuthToken = process.env.API_AUTH_TOKEN || '';
+const apiAuthDisabled = process.env.API_AUTH_DISABLED === 'true';

 if (!runtimeApiKey) {
  console.warn('GEMINI_API_KEY/API_KEY is not set. API calls will fail until it is configured.');
@@ -70,11 +71,19 @@ app.use((req, res, next) => {
 app.use(express.json({ limit: process.env.API_JSON_LIMIT || '50mb' }));

 function requireAuth(req: express.Request, res: express.Response, next: express.NextFunction) {
-  if (!apiAuthToken) {
+  if (apiAuthDisabled) {
    next();
    return;
  }

+  if (!apiAuthToken) {
+    res.status(503).json({
+      ok: false,
+      error: 'API_AUTH_TOKEN is required. Set it in .env.local, or set API_AUTH_DISABLED=true for local-only development.',
+    });
+    return;
+  }
+
  const authHeader = req.header('authorization') || '';
  const bearerToken = authHeader.startsWith('Bearer ') ? authHeader.slice(7) : '';
  const headerToken = req.header('x-api-key') || '';
@@ -86,7 +95,7 @@ function requireAuth(req: express.Request, res: express.Response, next: express.

  res.status(401).json({
    ok: false,
-    error: 'Unauthorized. Send Authorization: Bearer <API_AUTH_TOKEN> or x-api-key.',
+    error: 'Unauthorized. Send Authorization: Bearer YOUR_API_AUTH_TOKEN or x-api-key.',
  });
 }

@@ -323,7 +332,8 @@ app.get('/api/health', (_req, res) => {
    ok: true,
    apiPort,
    hasGeminiApiKey: Boolean(runtimeApiKey),
-    authEnabled: Boolean(apiAuthToken),
+    authEnabled: Boolean(apiAuthToken) && !apiAuthDisabled,
+    authRequired: !apiAuthDisabled,
    acceptsPerRequestApiKey: true,
    defaultImageModel,
    defaultTextModel,
@@ -336,7 +346,8 @@ app.get('/api/config', requireAuth, (_req, res) => {
    apiPort,
    hasGeminiApiKey: Boolean(runtimeApiKey),
    apiKeyPreview: runtimeApiKey ? `${runtimeApiKey.slice(0, 6)}...${runtimeApiKey.slice(-4)}` : '',
-    authEnabled: Boolean(apiAuthToken),
+    authEnabled: Boolean(apiAuthToken) && !apiAuthDisabled,
+    authRequired: !apiAuthDisabled,
    defaultImageModel,
    defaultTextModel,
  });