H0-02 为 /internal/* 增加 InternalAuthGuard #47

New Issue

wangdl · 2026-05-24T21:49:32+08:00

wangdl commented

2026-05-24 21:49:32 +08:00

目标

修复 /internal/* 端点无认证暴露的安全漏洞，确保内部接口仅能被内部服务调用。

背景说明

当前 /internal/* 下有 7 个端点无认证暴露，可被外部直接访问——读取文档原文、写入 chunks/candidates、劫持导入作业。这是严重的安全高危问题，必须在 iOS 对接前修复。

模块职责

请设计和实现以下安全措施：

添加 InternalAuthGuard，使用 INTERNAL_API_KEY 或服务间签名机制
Nginx 层限制公网访问 /internal/*，优先只允许内网 / Worker 调用
移除 internal-rag.controller 上不安全的 @Public 装饰器（如果存在）
验证未带内部认证凭证时全部返回 401/403
提供内部服务调用的认证方式说明

禁止事项

禁止在修复完成前继续暴露 /internal/* 端点
不建议把 InternalAuthGuard 设计成可选的中间件

## 目标修复 /internal/* 端点无认证暴露的安全漏洞，确保内部接口仅能被内部服务调用。 ## 背景说明当前 /internal/* 下有 7 个端点无认证暴露，可被外部直接访问——读取文档原文、写入 chunks/candidates、劫持导入作业。这是严重的安全高危问题，必须在 iOS 对接前修复。 ## 模块职责请设计和实现以下安全措施： 1. 添加 InternalAuthGuard，使用 INTERNAL_API_KEY 或服务间签名机制 2. Nginx 层限制公网访问 /internal/*，优先只允许内网 / Worker 调用 3. 移除 internal-rag.controller 上不安全的 @Public 装饰器（如果存在） 4. 验证未带内部认证凭证时全部返回 401/403 5. 提供内部服务调用的认证方式说明 ## 禁止事项 - 禁止在修复完成前继续暴露 /internal/* 端点 - 不建议把 InternalAuthGuard 设计成可选的中间件

wangdl added this to the H0：iOS 对接阻断修复（P0） milestone 2026-05-24 21:49:32 +08:00

wangdl commented

2026-05-24 22:06:45 +08:00

✅ H0-02 修复完成

问题

/internal/* 7 个端点零认证暴露公网，可读取文档原文、写入 chunks/candidates、劫持导入作业。

修改

文件	变更
`src/common/guards/internal-auth.guard.ts`	新建 — InternalAuthGuard，验证 `X-Internal-API-Key` 请求头，对比 `INTERNAL_API_KEY` 或 `RAG_WORKER_SECRET` 环境变量
`src/modules/rag/internal-rag.controller.ts`	移除 `@Public()` 装饰器，替换为 `@UseGuards(InternalAuthGuard)`
`test/h0.e2e-spec.ts`	新增 H0-02 相关 6 个测试用例

保护的端点

方法	路径	修改前	修改后
GET	`/internal/rag/jobs/next`	公开	需 Internal Key
GET	`/internal/rag/jobs/:id`	公开	需 Internal Key
POST	`/internal/rag/jobs/:id/claim`	公开	需 Internal Key
POST	`/internal/rag/jobs/:id/heartbeat`	公开	需 Internal Key
POST	`/internal/rag/jobs/:id/status`	公开	需 Internal Key
POST	`/internal/rag/chunks`	公开	需 Internal Key
POST	`/internal/rag/candidates`	公开	需 Internal Key

认证方式

请求需携带 Header：X-Internal-API-Key: <secret>

环境变量优先级：INTERNAL_API_KEY > RAG_WORKER_SECRET

测试

npx jest --config ./test/jest-e2e.json --testPathPatterns="h0" --forceExit
# 10/10 passing（含 H0-01 4 个 + H0-02 6 个）

上线注意

生产环境已有 RAG_WORKER_SECRET，Worker 无需改动
建议额外在 Nginx 层限制 /internal/ 仅允许 127.0.0.1 访问（纵深防御）
CI/CD 中的 RAG_WORKER_SECRET 需确认已配置

## ✅ H0-02 修复完成 ### 问题 `/internal/*` 7 个端点零认证暴露公网，可读取文档原文、写入 chunks/candidates、劫持导入作业。 ### 修改 | 文件 | 变更 | |------|------| | `src/common/guards/internal-auth.guard.ts` | **新建** — InternalAuthGuard，验证 `X-Internal-API-Key` 请求头，对比 `INTERNAL_API_KEY` 或 `RAG_WORKER_SECRET` 环境变量 | | `src/modules/rag/internal-rag.controller.ts` | 移除 `@Public()` 装饰器，替换为 `@UseGuards(InternalAuthGuard)` | | `test/h0.e2e-spec.ts` | 新增 H0-02 相关 6 个测试用例 | ### 保护的端点 | 方法 | 路径 | 修改前 | 修改后 | |------|------|--------|--------| | GET | `/internal/rag/jobs/next` | 公开 | 需 Internal Key | | GET | `/internal/rag/jobs/:id` | 公开 | 需 Internal Key | | POST | `/internal/rag/jobs/:id/claim` | 公开 | 需 Internal Key | | POST | `/internal/rag/jobs/:id/heartbeat` | 公开 | 需 Internal Key | | POST | `/internal/rag/jobs/:id/status` | 公开 | 需 Internal Key | | POST | `/internal/rag/chunks` | 公开 | 需 Internal Key | | POST | `/internal/rag/candidates` | 公开 | 需 Internal Key | ### 认证方式请求需携带 Header：`X-Internal-API-Key: <secret>` 环境变量优先级：`INTERNAL_API_KEY` > `RAG_WORKER_SECRET` ### 测试 ```bash npx jest --config ./test/jest-e2e.json --testPathPatterns="h0" --forceExit # 10/10 passing（含 H0-01 4 个 + H0-02 6 个） ``` ### 上线注意 - 生产环境已有 `RAG_WORKER_SECRET`，Worker 无需改动 - 建议额外在 Nginx 层限制 `/internal/` 仅允许 127.0.0.1 访问（纵深防御） - CI/CD 中的 `RAG_WORKER_SECRET` 需确认已配置

wangdl referenced this issue

2026-05-24 22:27:35 +08:00

H0-07 修复后跑核心 CAPI E2E + 输出 iOS 对接文档 #52

wangdl closed this issue

2026-06-05 20:17:14 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: wangdl/api-server#47