feat: add OpenAPI access control and configuration

oiov · oiov · commit 00a8eb89d06c · 2026-04-23T20:37:50.000+08:00
- Introduced `openApiEnabled` configuration in the app settings.
- Implemented middleware to restrict access to API routes when OpenAPI is disabled.
- Updated API key creation logic to check OpenAPI status before proceeding.
- Added user feedback for disabled API access in the frontend.
- Created tests for OpenAPI functionality and response handling.
- Updated environment configuration to include `ENABLE_OPENAPI` variable.
diff --git a/README.md b/README.md
@@ -77,9 +77,10 @@
 -   `EMAIL_DOMAIN`: 您的邮箱域名，例如 `example.com,example.net`。
 -   `TURNSTILE_KEY`: 您的 Turnstile 站点密钥，可选。
 -   `TURNSTILE_SECRET`: 您的 Turnstile 密钥，可选。
--   `PASSWORD`: 站点访问密码（可选）。
--   `API_RATE_LIMIT_PER_MINUTE`: API 每分钟请求限制（可选，默认 100）。
--   `SHOW_AFF`: 是否展示推广弹框和常驻推广链接（可选，`true` 开启，默认不展示）。
+-   `PASSWORD`: 站点访问密码（可选）。
+-   `API_RATE_LIMIT_PER_MINUTE`: API 每分钟请求限制（可选，默认 100）。
+-   `SHOW_AFF`: 是否展示推广弹框和常驻推广链接（可选，`true` 开启，默认不展示）。
+-   `ENABLE_OPENAPI`: 是否开启 OpenAPI 调用功能（可选，默认开启；设置为 `false` 时禁用 API Key 创建与 `/api/v1/*` 调用）。
 
 ## 🔨 本地运行调试
 
diff --git a/README_en.md b/README_en.md
@@ -133,6 +133,7 @@ When deploying to Cloudflare Pages, you need to configure the following environm
 -   `PASSWORD`: Site access password (optional).
 -   `API_RATE_LIMIT_PER_MINUTE`: API rate limit per minute (optional, default 100).
 -   `SHOW_AFF`: Show promotional popup and link (optional, `true` to enable, hidden by default).
+-   `ENABLE_OPENAPI`: Whether to enable OpenAPI access (optional, enabled by default; set to `false` to disable API key creation and `/api/v1/*` access).
 
 ## Community Group
 
@@ -144,4 +145,4 @@ GNU General Public License v3.0
 
 ## Star History
 
-[![Star History Chart](https://api.star-history.com/svg?repos=oiov/vmail&type=Date)](https://star-history.com/#oiov/vmail&Date)
+[![Star History Chart](https://api.star-history.com/svg?repos=oiov/vmail&type=Date)](https://star-history.com/#oiov/vmail&Date)
diff --git a/docs/ai-deploy.md b/docs/ai-deploy.md
@@ -9,7 +9,7 @@
 
 部署后关键接口合同：
 
-- `GET /config` 返回：`turnstileEnabled`、`sitePasswordEnabled`、`apiRateLimitPerMinute`
+- `GET /config` 返回：`turnstileEnabled`、`sitePasswordEnabled`、`apiRateLimitPerMinute`、`openApiEnabled`
 - `GET /api/stats` 返回：`totals`、`today`、`yesterday`
 - `POST /auth/unlock`、`GET /auth/status`、`POST /auth/logout`
 
@@ -37,12 +37,14 @@
 - `TURNSTILE_SECRET`（可选）
 - `PASSWORD`（可选；为空时站点默认公开）
 - `API_RATE_LIMIT_PER_MINUTE`（可选；非法值或缺省回退到 `100`）
+- `ENABLE_OPENAPI`（可选；默认开启，设置为 `false` 时禁用 API Key 创建与 `/api/v1/*`）
 
 行为说明：
 
 - 当 `TURNSTILE_KEY` 和 `TURNSTILE_SECRET` 任一缺失时，前后端都进入“无需人机验证”模式。
 - 当 `PASSWORD` 为空时，前端不会出现站点解锁门禁；有值时需要先解锁站点。
 - `API_RATE_LIMIT_PER_MINUTE` 作用于 v1 API Key 中间件，按“每个 API Key、每分钟固定窗口”限流。
+- 当 `ENABLE_OPENAPI=false` 时，`/api/api-keys` 与 `/api/v1/*` 会统一返回 `403 OPENAPI_DISABLED`，`/api-docs` 页面仅展示提示。
 
 # 4. 数据库迁移与基础初始化
 
@@ -88,6 +90,7 @@
      - `turnstileEnabled`
      - `sitePasswordEnabled`
      - `apiRateLimitPerMinute`
+     - `openApiEnabled`
 2. 统计合同：
    - 请求 `GET /api/stats`
    - 断言返回结构含 `totals/today/yesterday`
@@ -104,8 +107,10 @@
    - 使用同一 API Key 连续请求 v1 API
    - 超过阈值返回 `429`
    - 响应头包含：`X-RateLimit-Limit`、`X-RateLimit-Remaining`、`Retry-After`
+   - 若 `ENABLE_OPENAPI=false`：`/api/api-keys` 与 `/api/v1/*` 返回 `403`
 6. 前端展示：
    - 首页 SiteStats 卡片显示增长率（today vs yesterday）
+   - `/api-docs` 在 `openApiEnabled=false` 时展示禁用提示
 
 # 7. 常见问题与回滚策略
 
diff --git a/docs/github-action-tutorial.md b/docs/github-action-tutorial.md
@@ -24,6 +24,7 @@
 | `TURNSTILE_SECRET` | 可选，Cloudflare Turnstile 密钥 (Secret Key)。                                                           | `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`       |
 | `PASSWORD`         | 可选，用于访问 Vmail 网站的密码。                                                                    | `password`                             |
 | `API_RATE_LIMIT_PER_MINUTE` | 可选，API 每分钟请求限制，默认为 `100`。                                                        | `100`                                  |
+| `ENABLE_OPENAPI`   | 可选，是否开启 OpenAPI 调用功能；默认为开启，设置为 `false` 时禁用 API Key 创建和 `/api/v1/*`。     | `false`                                |
 
 ## 触发自动部署
 
@@ -39,4 +40,4 @@
 ## 注意事项
 
 - 工作流文件 (`.github/workflows/deploy.yml`) 会自动从您的 Secrets 中读取配置并应用到 `wrangler.toml` 文件中，**请勿**直接将敏感信息写入 `wrangler.toml` 文件。
-- 如果您的数据库结构有变更（例如，修改了 `worker/src/database/schema.ts`），请记得生成新的迁移文件并提交到代码库中，GitHub Action 会自动帮您应用更新。
+- 如果您的数据库结构有变更（例如，修改了 `worker/src/database/schema.ts`），请记得生成新的迁移文件并提交到代码库中，GitHub Action 会自动帮您应用更新。
diff --git a/frontend/build/client/assets/main-Bd6k8RJl.css b/frontend/build/client/assets/main-Bd6k8RJl.css
diff --git a/frontend/build/client/assets/main-EhQP4hi8.css b/frontend/build/client/assets/main-EhQP4hi8.css
diff --git a/frontend/build/client/assets/main-g6v1k0ut.js b/frontend/build/client/assets/main-g6v1k0ut.js
diff --git a/frontend/build/client/index.html b/frontend/build/client/index.html
@@ -5,8 +5,8 @@
     <link rel="icon" type="image/x-icon" href="/favicon.ico" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>VMAIL - Virtual Temporary Email</title>
-    <script type="module" crossorigin src="/assets/main-BdocldXg.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/main-Bd6k8RJl.css">
+    <script type="module" crossorigin src="/assets/main-g6v1k0ut.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/main-EhQP4hi8.css">
   </head>
   <script
     defer
diff --git a/frontend/src/hooks/useConfig.ts b/frontend/src/hooks/useConfig.ts
@@ -7,6 +7,7 @@ export interface AppConfig {
   turnstileEnabled: boolean;
   sitePasswordEnabled: boolean;
   apiRateLimitPerMinute: number;
+  openApiEnabled: boolean;
   // feat: 添加 cookiesSecret 到配置中，以便前端加密时使用
   cookiesSecret: string;
   // feat: 控制是否展示推广弹框和常驻链接
@@ -23,4 +24,4 @@ export const useConfig = () => {
     throw new Error('useConfig 必须在 ConfigProvider 内部使用');
   }
   return context;
-};
+};
diff --git a/frontend/src/pages/ApiDocs.tsx b/frontend/src/pages/ApiDocs.tsx
@@ -253,6 +253,11 @@ API requests are rate limited based on your API Key configuration. Default limit
 
   // 创建 API Key
   const handleCreateApiKey = async () => {
+    if (!config.openApiEnabled) {
+      toast.error("API access is currently disabled");
+      return;
+    }
+
     if (!turnstileToken) {
       toast.error(t("Please complete the verification first"));
       return;
@@ -474,6 +479,11 @@ API requests are rate limited based on your API Key configuration. Default limit
               Vmail & NBility 联动注册送 Claude Code、Codex 免费额度
             </button>
           )}
+          {!config.openApiEnabled && (
+            <div className="mt-4 rounded-lg border border-amber-500/40 bg-amber-500/10 px-4 py-3 text-sm text-amber-100">
+              当前管理员已禁用 API 访问，若有需要请自行部署。
+            </div>
+          )}
         </div>
 
         {/* Get API Key Section */}
@@ -539,6 +549,11 @@ API requests are rate limited based on your API Key configuration. Default limit
                     "Create a free API Key to access the API. Each key has a rate limit of 100 requests per minute.",
                   )}
                 </p>
+                {!config.openApiEnabled && (
+                  <p className="mb-4 rounded-lg border border-amber-500/30 bg-amber-500/10 px-3 py-2 text-sm text-amber-100">
+                    当前实例已关闭 API 调用与 API Key 创建功能。
+                  </p>
+                )}
                 <div className="space-y-4">
                   <div>
                     <label className="block text-sm text-gray-400 mb-2">
@@ -566,7 +581,7 @@ API requests are rate limited based on your API Key configuration. Default limit
                   </div>
                   <button
                     onClick={handleCreateApiKey}
-                    disabled={!turnstileToken || isCreating}
+                    disabled={!config.openApiEnabled || !turnstileToken || isCreating}
                     className="px-6 py-2.5 bg-cyan-600 hover:bg-cyan-700 disabled:bg-gray-600 disabled:cursor-not-allowed rounded-lg font-medium transition-colors">
                     {isCreating ? t("Creating...") : t("Create API Key")}
                   </button>
diff --git a/worker/src/api/v1/index.ts b/worker/src/api/v1/index.ts
@@ -3,12 +3,16 @@ import { cors } from 'hono/cors';
 import type { Env } from '../../index';
 import { apiKeyAuth } from './middleware/apiKeyAuth';
 import mailboxesRouter from './routes/mailboxes';
+import { requireOpenApi } from '../../openapi';
 
 const v1 = new Hono<{ Bindings: Env }>();
 
 // 配置 CORS
 v1.use('/*', cors());
 
+// OpenAPI 开关关闭时，统一在认证前拦截所有 v1 请求
+v1.use('/*', requireOpenApi);
+
 // 所有 v1 路由都需要 API Key 认证
 v1.use('/*', apiKeyAuth);
 
diff --git a/worker/src/index.ts b/worker/src/index.ts
@@ -11,6 +11,7 @@ import PostalMime from 'postal-mime';
 import { decrypt } from './utils';
 // 导入 v1 API
 import v1Api from './api/v1';
+import { isOpenApiEnabled, requireOpenApi } from './openapi';
 
 
 // 定义 Cloudflare 绑定和环境变量的类型
@@ -26,6 +27,7 @@ export interface Env {
   PASSWORD?: string;
   API_RATE_LIMIT_PER_MINUTE?: string;
   SHOW_AFF?: string;
+  ENABLE_OPENAPI?: string;
 }
 
 // 初始化 Hono 应用
@@ -169,7 +171,7 @@ function generateApiKey(): string {
 }
 
 // 创建 API Key 接口（需要 Turnstile 验证）
-api.post('/api-keys', turnstile, async (c) => {
+api.post('/api-keys', requireOpenApi, turnstile, async (c) => {
   const db = getD1DB(c.env.DB);
   const body = c.get('parsedBody') as { name?: string };
 
@@ -326,6 +328,7 @@ app.get('/config', (c) => {
   // feat: 将 emailDomain 拆分为数组以支持多域名
   const emailDomain = c.env.EMAIL_DOMAIN ? c.env.EMAIL_DOMAIN.split(',').map(d => d.trim()) : [];
   const turnstileEnabled = isTurnstileEnabled(c.env);
+  const openApiEnabled = isOpenApiEnabled(c.env);
 
   return c.json({
     emailDomain: emailDomain, // 返回域名数组
@@ -334,6 +337,7 @@ app.get('/config', (c) => {
     cookiesSecret: c.env.COOKIES_SECRET,
     sitePasswordEnabled: Boolean(c.env.PASSWORD),
     apiRateLimitPerMinute: parseRateLimitPerMinute(c.env),
+    openApiEnabled,
     showAff: c.env.SHOW_AFF === 'true',
   });
 });
diff --git a/worker/src/openapi.test.ts b/worker/src/openapi.test.ts
@@ -0,0 +1,27 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createOpenApiDisabledResponse, isOpenApiEnabled } from './openapi.ts';
+
+function createEnv(overrides: { ENABLE_OPENAPI?: string } = {}) {
+  return overrides;
+}
+
+test('OpenAPI access is enabled by default when env var is missing', () => {
+  assert.equal(isOpenApiEnabled(createEnv()), true);
+});
+
+test('OpenAPI access is disabled only when ENABLE_OPENAPI is false', () => {
+  assert.equal(isOpenApiEnabled(createEnv({ ENABLE_OPENAPI: 'false' })), false);
+  assert.equal(isOpenApiEnabled(createEnv({ ENABLE_OPENAPI: 'FALSE' })), false);
+  assert.equal(isOpenApiEnabled(createEnv({ ENABLE_OPENAPI: 'true' })), true);
+});
+
+test('disabled response uses the shared OpenAPI disabled error format', async () => {
+  const response = createOpenApiDisabledResponse();
+
+  assert.equal(response.status, 403);
+  assert.equal(response.headers.get('Content-Type'), 'application/json');
+  const body = await response.json() as { error?: { code?: string; message?: string } };
+  assert.equal(body.error?.code, 'OPENAPI_DISABLED');
+  assert.match(body.error?.message ?? '', /disabled/i);
+});
diff --git a/worker/src/openapi.ts b/worker/src/openapi.ts
@@ -0,0 +1,37 @@
+import type { Context, Next } from 'hono';
+
+interface OpenApiEnv {
+  ENABLE_OPENAPI?: string;
+}
+
+export function isOpenApiEnabled(env: OpenApiEnv): boolean {
+  return env.ENABLE_OPENAPI?.trim().toLowerCase() !== 'false';
+}
+
+export function createOpenApiDisabledResponse(): Response {
+  return new Response(
+    JSON.stringify({
+      error: {
+        code: 'OPENAPI_DISABLED',
+        message: 'OpenAPI access is disabled by the site administrator. Please self-host Vmail if you need API access.',
+      },
+    }),
+    {
+      status: 403,
+      headers: {
+        'Content-Type': 'application/json',
+      },
+    },
+  );
+}
+
+export async function requireOpenApi(
+  c: Context<{ Bindings: OpenApiEnv }>,
+  next: Next,
+) {
+  if (!isOpenApiEnabled(c.env)) {
+    return createOpenApiDisabledResponse();
+  }
+
+  await next();
+}
diff --git a/wrangler.toml b/wrangler.toml
@@ -24,6 +24,7 @@ TURNSTILE_SECRET = "${TURNSTILE_SECRET}"
 PASSWORD = "${PASSWORD}"
 API_RATE_LIMIT_PER_MINUTE = "${API_RATE_LIMIT_PER_MINUTE}"
 SHOW_AFF = "${SHOW_AFF}"
+ENABLE_OPENAPI = "${ENABLE_OPENAPI}"
 
 # 配置邮件处理
 [triggers]
@@ -36,4 +37,4 @@ command = "pnpm run build"
 # 静态资源配置
 [assets]
 binding = "ASSETS"
-directory = "frontend/build/client"
+directory = "frontend/build/client"
