HMS 生产环境安全要点:租户隔离、API密钥与Gateway配额的完整清单
HMS 生产环境安全要点:租户隔离、API密钥与Gateway配额的完整清单
HMS(Holographic Memory System,全息记忆系统)是 AI 应用的长期记忆层:它负责保留对话与文档、提取事实、关联实体,并在后续推理时召回上下文。当 HMS 面向外部用户或供应商上线时,生产环境安全的核心是三件事:租户隔离、API 密钥分级管理、Gateway 配额与限流。本文结合仓库内的部署文件,整理出一份可直接执行的生产安全完整清单。
HMS 的官方供应商部署拓扑只开放一个入口,所有流量都必须经过 Gateway:
vendor -> nginx -> hms-vendor-gateway:18081 -> hms-api:18080 -> postgres:5432
一、生产拓扑:只暴露一个入口 🔒
安全的第一原则是最小暴露面。在 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 中可以直接看到并调整。两个生产注意点:
- 限流与配额状态目前保存在内存中,网关重启后计数器清零。小规模演示可以接受,生产环境建议把配额与限流状态迁移到 Redis 或 Postgres;
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冒烟测试。
延伸阅读
- 供应商部署总览:README_VENDOR_DEPLOY.md
- 网关设计与安全层说明:vendor_sdk/GATEWAY.md
- 环境与参数模板:.env.example
- 租户扩展源码:core/dataplane/hms_api/extensions/
- 冒烟测试脚本:scripts/smoke_test.sh
