fix: 修复 OpenAPI 文档生产环境显示 localhost 问题

.env.example

@@ -15,6 +15,8 @@ DB_NAME=claude_code_hub
 
 # 应用配置
 APP_PORT=23000
+APP_URL=                                   # 应用访问地址（留空自动检测，生产环境建议显式配置）
+                                           # 示例：https://your-domain.com 或 http://192.168.1.100:23000
 
 # Cookie 安全策略
 # 功能说明：控制是否强制 HTTPS Cookie（设置 cookie 的 secure 属性）

CLAUDE.md

@@ -320,6 +320,9 @@ ENABLE_CODEX_INSTRUCTIONS_INJECTION=false  # 是否强制替换 Codex 请求的
 
 # 应用配置
 APP_PORT=23000                     # 应用端口
+APP_URL=                           # 应用访问地址（留空自动检测，生产环境建议显式配置）
+                                   # 示例：https://your-domain.com 或 http://192.168.1.100:23000
+                                   # 用于 OpenAPI 文档的 server URL 配置
 NODE_ENV=production                # 环境模式
 TZ=Asia/Shanghai                   # 时区设置
 LOG_LEVEL=info                     # 日志级别
@@ -360,6 +363,23 @@ ENABLE_SECURE_COOKIES=0        # 正确:也可以用 0
    - 必须设置 `ENABLE_SECURE_COOKIES=false` 才能正常使用
    - 或者配置 HTTPS 反向代理(推荐)
 
+#### OpenAPI 文档地址配置
+
+OpenAPI 文档（`/api/actions/scalar` 和 `/api/actions/docs`）中的 server URL 配置：
+
+**配置方式**：
+- **生产环境（推荐）**：显式设置 `APP_URL` 环境变量
+  ```bash
+  APP_URL=https://your-domain.com  # HTTPS 域名
+  APP_URL=http://192.168.1.100:23000  # HTTP IP + 端口
+  ```
+
+- **开发环境**：留空即可，自动使用 `http://localhost:13500`
+
+**效果**：
+- 配置后，OpenAPI 文档中的 "Try it out" 功能会自动使用正确的地址
+- 避免生产环境显示 `http://localhost`，导致 API 测试失败
+
 ## 开发注意事项
 
 ### 1. Redis 依赖和降级策略

src/app/api/actions/[...route]/route.ts

@@ -623,6 +623,40 @@ app.openapi(testWebhookRoute, testWebhookHandler);
 
 // ==================== OpenAPI 文档 ====================
 
+/**
+ * 生成 OpenAPI servers 配置（动态检测）
+ */
+function getOpenAPIServers() {
+  const servers: Array<{ url: string; description: string }> = [];
+
+  // 优先使用环境变量配置的 APP_URL
+  const appUrl = process.env.APP_URL;
+  if (appUrl) {
+    servers.push({
+      url: appUrl,
+      description: "应用地址 (配置)",
+    });
+  }
+
+  // 降级：添加常见的开发环境地址
+  if (process.env.NODE_ENV !== "production") {
+    servers.push({
+      url: "http://localhost:13500",
+      description: "本地开发环境",
+    });
+  }
+
+  // 兜底：如果没有配置，提供占位符提示
+  if (servers.length === 0) {
+    servers.push({
+      url: "https://your-domain.com",
+      description: "生产环境 (请配置 APP_URL 环境变量)",
+    });
+  }
+
+  return servers;
+}
+
 // 生成 OpenAPI 3.1.0 规范文档
 app.doc("/openapi.json", {
   openapi: "3.1.0",
@@ -677,16 +711,7 @@ HTTP 状态码:
 - \`500\`: 服务器内部错误
     `,
   },
-  servers: [
-    {
-      url: "http://localhost:13500",
-      description: "本地开发环境",
-    },
-    {
-      url: "https://your-domain.com",
-      description: "生产环境",
-    },
-  ],
+  servers: getOpenAPIServers(),
   tags: [
     { name: "用户管理", description: "用户的 CRUD 操作和限额管理" },
     { name: "密钥管理", description: "API 密钥的生成、编辑和限额配置" },