HMS 生产环境安全要点:租户隔离、API密钥与Gateway配额的完整清单

原创2026-10-28 15:06:111,352 阅读

HMS 生产环境安全要点:租户隔离、API密钥与Gateway配额的完整清单

HMS(Holographic Memory System,全息记忆系统)是 AI 应用的长期记忆层:它负责保留对话与文档、提取事实、关联实体,并在后续推理时召回上下文。当 HMS 面向外部用户或供应商上线时,生产环境安全的核心是三件事:租户隔离、API 密钥分级管理、Gateway 配额与限流。本文结合仓库内的部署文件,整理出一份可直接执行的生产安全完整清单。

HMS 的官方供应商部署拓扑只开放一个入口,所有流量都必须经过 Gateway:

vendor -> nginx -> hms-vendor-gateway:18081 -> hms-api:18080 -> postgres:5432

HMS 全息记忆系统横幅:生产环境安全部署架构示意

一、生产拓扑:只暴露一个入口 🔒

安全的第一原则是最小暴露面。在 docker-compose.yml 中可以看到:

  • 只有 Nginx 对公网开放(默认 8080 端口),其余服务全部位于内部 Docker 网络 hms-internal 中;
  • hms-api 的 18080 端口只绑定到 127.0.0.1,外部无法直连;
  • postgres 的 5432 端口完全不发布到宿主机。

Nginx 层(docker/nginx.conf)还叠加了第一道防线:limit_req 按 IP 限流(10r/s,burst 30)、请求体上限 client_max_body_size 5m、JSON 格式的访问日志,以及 650 秒的代理超时以适配长记忆任务。

⚠️ 永远不要将 hms-api:18080 或 postgres:5432 直接暴露到公网。

生产环境上线前,请用仓库提供的 TLS 模板替换默认 HTTP 配置:docker/nginx.tls.example.conf,并把 PUBLIC_BASE_URL 改为 https:// 域名。

二、租户隔离:bank_id 与数据库 Schema 双重边界

HMS 用「记忆库」(bank)作为租户数据的基本边界,隔离分两层实现。

2.1 Gateway 层:按密钥哈希隔离 bank_id

当 HMS_GATEWAY_SCOPE_BANK_IDS=true(默认开启)时,供应商提交的公开 bank_id 会被 Gateway 自动改写为内部银行名:

vendor_<key_hash>_vendor-demo

也就是说,即使两家供应商都传入 vendor-demo,它们在内部对应的是完全不同的 HMS bank,互不可见;返回结果时再被重写回公开的 bank_id。该逻辑位于 vendor_sdk/src/hms_vendor_sdk/gateway.py。

同时,bank_id 会经过严格的格式校验:只能以字母或数字开头,仅允许字母、数字、下划线、短横线、点、冒号,最长 96 个字符,禁止斜杠与空格,从源头杜绝路径注入类问题。

2.2 API 层:租户扩展与数据库 Schema

HMS 数据平面通过「租户扩展」(Tenant Extension)在认证后返回一个 TenantContext,其中包含该租户使用的 PostgreSQL schema 名称,所有数据库查询都会使用该 schema 的全限定表名,实现数据库级的租户隔离。接口定义见 core/dataplane/hms_api/extensions/tenant.py,内置实现见 core/dataplane/hms_api/extensions/builtin/tenant.py。

生产启用 API Key 认证方式:

HMS_API_TENANT_EXTENSION=hms_api.extensions.builtin.tenant:ApiKeyTenantExtension
HMS_API_TENANT_API_KEY=<你的内部密钥>
HMS_API_DATABASE_SCHEMA=public   # 默认值

如果需要「每个租户一个 schema」的多租户形态,可按该接口的说明实现自定义 TenantExtension,根据 API Key 或 Token 声明查询对应 schema。

2.3 应用层建议

  • 为每个用户或组织分配一个稳定的 bank_id 边界,不要多个租户共用一个 bank;
  • 不要让不同供应商刻意共享同一个公开 bank_id。

三、API 密钥分级:三类密钥各司其职 🔑

HMS 供应商部署中至少存在四类凭据,分级管理、严禁越级下发是安全底线:

凭据 环境变量 应交给谁
供应商网关密钥 HMS_GATEWAY_API_KEYS(hms_live_*,逗号分隔,每商一个) 仅对应供应商
内部 HMS API 密钥 HMS_INTERNAL_API_KEY / HMS_API_TENANT_API_KEY 仅网关服务
模型服务商密钥 HMS_API_LLM_API_KEY 等 绝不下发,留在服务器
数据库凭据 POSTGRES_PASSWORD / HMS_API_DATABASE_URL 绝不下发

仓库提供了开箱即用的密钥生成脚本 scripts/generate_keys.sh:它会基于 openssl 随机生成 Postgres 密码、内部密钥和两个 hms_live_* 供应商密钥,并自动写回 .env,省去手工拼凑。

分发给供应商时,只给两样东西:

base_url = PUBLIC_BASE_URL
api_key  = 一份额属于它的 hms_live_* 密钥

HMS_INTERNAL_API_KEY、模型密钥、数据库凭据一律不得出现在 SDK 文件、前端代码或示例页面中。

四、Gateway 配额与限流参数清单 ⚙️

Gateway(vendor_sdk/GATEWAY.md)按「密钥哈希」维度执行限流与配额,超限返回 429:

参数 默认值 作用
HMS_GATEWAY_RATE_LIMIT_PER_MINUTE 60 单密钥每分钟滑动窗口限流,超限返回 429 Rate limit exceeded.
HMS_GATEWAY_DAILY_QUOTA 1000 单密钥每日(UTC)请求配额,超限返回 429 Daily quota exceeded.
HMS_GATEWAY_MAX_SESSIONS_PER_REQUEST 100 单次请求最大会话数,超出返回 413
HMS_GATEWAY_MAX_MESSAGES_PER_SESSION 100 单会话最大消息数
HMS_GATEWAY_MAX_MESSAGE_CHARS 20000 单条消息最大字符数
HMS_GATEWAY_MAX_QUESTION_CHARS 4000 召回问题的最大长度

这些默认值都在 .env.example 中可以直接看到并调整。两个生产注意点:

  1. 限流与配额状态目前保存在内存中,网关重启后计数器清零。小规模演示可以接受,生产环境建议把配额与限流状态迁移到 Redis 或 Postgres;
  2. HMS_GATEWAY_API_KEYS 是静态逗号分隔列表。供应商较多时,建议把密钥元数据(属主、配额、状态、轮换时间)迁入数据库管理,并定期轮换每个供应商的 hms_live_* 密钥,绝不跨公司复用。

五、审计日志与敏感信息脱敏 📝

Gateway 会把每次请求写入 JSONL 审计日志(默认 ./logs/vendor_gateway_audit.jsonl),记录动作类型、密钥哈希、bank_id、耗时与召回结果数。落盘前会执行自动脱敏(gateway.py):

  • api_key、authorization、token、secret、password 等字段整体替换为 <redacted>;
  • 正文中的 sk-*、hms_live_*/hms_test_*、Bearer 令牌、邮箱地址被正则遮蔽;
  • 超过 600 字符的长文本自动截断。

生产建议把审计日志从本地文件升级为对象存储或集中式日志系统,并设定保留策略。上线后可运行 scripts/smoke_test.sh 做基础验证:健康检查、缺失密钥返回 401、以及 /v1/vendor/organize 返回 evidence_packet 三项断言。

六、上线前安全检查清单 ✅

最后,对照下面这份清单逐项打勾:

  • [ ] 已运行 bash scripts/generate_keys.sh,.env 中所有 *_change_me 占位值已替换;
  • [ ] 填充后的 .env、密钥、令牌没有提交进 Git;
  • [ ] 仅 Nginx 对公网开放;hms-api:18080 只绑定本地回环,Postgres 未暴露端口;
  • [ ] 已用 docker/nginx.tls.example.conf 启用 TLS;
  • [ ] 每个供应商持有独立的 hms_live_* 密钥,且 HMS_GATEWAY_SCOPE_BANK_IDS=true 保持开启;
  • [ ] 已按业务量调整 HMS_GATEWAY_RATE_LIMIT_PER_MINUTE 与 HMS_GATEWAY_DAILY_QUOTA;
  • [ ] 模型密钥与数据库凭据只存在于服务器环境变量中;
  • [ ] 已为 ./volumes/postgres 和 ./logs/vendor_gateway_audit.jsonl 配置备份;
  • [ ] 已跑通 bash scripts/smoke_test.sh 冒烟测试。

延伸阅读

登录后查看全文
HMS