内容
# NIM 密钥管理器
<img width="1200" height="630" alt="NIM-KE~1" src="https://github.com/user-attachments/assets/1dc02b55-1a6d-41ff-a76b-14abb53a853d" />
**用于管理您自己的 NVIDIA Build/NIM 账户的 API 密钥的自主托管、生产就绪的密钥管理器** — 加密存储、辅助轮换、到期检测、使用统计、项目、基于角色的访问控制、审计、网页仪表盘和 **Claude MCP 连接器**。几分钟内部署您自己的实例；所有配置均通过环境变量完成。
[](https://github.com/BySergiMM/nim-key-manager/actions/workflows/ci.yml)
[](LICENSE)
[](https://www.python.org/)
[](#开发与测试)
> **NVIDIA 服务条款。** NVIDIA Build **没有提供公共 API** 来以编程方式创建或轮换密钥（您在 [build.nvidia.com](https://build.nvidia.com/settings/api-keys) 上生成它们），并且 API 密钥 **不得与第三方共享或重新分发**。因此，该项目旨在 **您在自己的实例上管理自己的密钥**：唯一的出站调用是官方的只读 **验证** 端点 `GET https://integrate.api.nvidia.com/v1/models`。它不自动化或爬取 NVIDIA 门户，也 **不是** 一个用于向其他人提供密钥的服务。
## 部署您自己的实例（无需本地设置）
[](https://render.com/deploy?repo=https://github.com/BySergiMM/nim-key-manager)
1. 点击按钮（或 **使用此模板 → 创建仓库**，然后在 [Render](https://render.com) 上选择 **新建 → 蓝图** 并选择您的复刻）。Render 读取 [`render.yaml`](render.yaml) 并自动配置 **所有内容**：
- 一个托管的 PostgreSQL 数据库，
- 带有健康检查的 Dockerized 网络服务，
- 机密 `JWT_SECRET`、`ENCRYPTION_MASTER_KEY` 和 `MCP_OAUTH_JWT_SIGNING_KEY`（由 Render 的机密管理器生成和存储），
- 从数据库注入的 `DATABASE_URL`。
2. 在提示时，设置 `FIRST_ADMIN_EMAIL` 和 `FIRST_ADMIN_PASSWORD`（您的初始管理员，在首次启动时创建）。
3. 打开服务网址：在 `/` 登录，在 `/docs` 上探索 API。
4. 对 `main` 的每次推送都会运行 CI（lint + 类型 + 测试 + 构建）并自动重新部署。迁移（`alembic upgrade head`）在容器启动时运行。
您更喜欢其他主机吗？任何运行 Docker 容器 + PostgreSQL 的平台都可以使用 — 请参见 [`docs/deployment.md`](docs/deployment.md)。
## 从 Claude 使用（MCP 连接器）
相同的部署在 `‹BASE›/mcp` 上公开了一个 **模型上下文协议服务器**，因此您可以将其作为 **Claude 的自定义连接器** 添加。Claude 通过 **OAuth 2.1**（默认为 GitHub，可选 Google）进行身份验证，并且可以列出/检查密钥、**发放** 一个现成的密钥、注册/轮换/吊销和管理项目 — 具有与 REST API 相同的基于角色的访问控制和审计跟踪。只有 `MCP_ALLOWED_IDENTITIES` 中的身份才能连接（失败关闭）。
1. 使用回调 `‹BASE›/auth/callback` 创建 GitHub **OAuth 应用程序**；复制客户端 ID/密钥。
2. 在 Render 中设置 `MCP_GITHUB_CLIENT_ID`、`MCP_GITHUB_CLIENT_SECRET` 和 `MCP_ALLOWED_IDENTITIES`（您的 GitHub 登录/电子邮件）。其余部分已在 `render.yaml` 中。
3. 在 Claude 中：**设置 → 连接器 → 添加自定义连接器** → URL `‹BASE›/mcp` → **连接**。
完整指南（Google、工具参考、安全性和故障排除）：[`docs/connector.md`](docs/connector.md)。
## 功能
- **安全密钥注册** — 使用 AES-256-GCM（密钥通过 HKDF-SHA256 从平台机密管理器导出）在静止时加密。绝不以明文存储或记录。
- **辅助审计轮换** — 您在 NVIDIA 账户中创建新密钥，粘贴它，系统执行原子交换（新密钥激活，旧密钥被撤销，带有 `rotated_from_id` 血统链接）。
- **到期检测** — 每小时后台作业 + 维护端点；可配置的 `expiring_soon` 标志。
- **定期验证** — 每 6 小时（可配置）自动扫描 NVIDIA 以标记无效/吊销的密钥。
- **密钥发放** — `GET /api/v1/keys/dispense` 返回最近最少使用（LRU）的活动密钥（全局或按项目），记录使用情况。
- **项目** — 按使用者/工作负载对密钥进行分组。
- **统计** — 按状态、发放、时间序列使用情况进行清点。
- **安全** — JWT（访问 + 刷新），角色 `admin`/`manager`/`viewer`，速率限制，每个敏感操作的不可变审计。
- **Claude 连接器（MCP）** — 在 `/mcp` 上的 OAuth 安全 MCP 服务器（参见上文）。
- **操作** — 结构化 JSON 日志，Prometheus 指标在 `/metrics`，健康检查在 `/health`，OpenAPI 在 `/docs`。
## 架构
```
app/
├── domain/ # 枚举和领域异常（无依赖）
├── application/ # 用例（服务）和端口（接口）
│ └── services/ # 认证、用户、密钥、项目、统计、审计
├── infrastructure/ # 适配器：SQLAlchemy（存储库）和 NVIDIA 网关
├── api/ # FastAPI：路由器、模式、依赖、速率限制
├── mcp/ # Claude 连接器：MCP 服务器、OAuth 和身份映射
├── dashboard/ # 在 / 处提供的轻量级单页应用
├── tasks/ # 调度作业（APScheduler）
└── core/ # 配置、加密、安全、日志记录
```
务实的干净架构：依赖关系指向内部；应用层不知道 FastAPI，并通过 `KeyValidator` 端口访问 NVIDIA。详细信息和决策在 [`docs/architecture.md`](docs/architecture.md) 中。
**技术栈**：Python 3.12 · FastAPI · FastMCP（Claude 连接器）· SQLAlchemy 2（异步）· 托管 PostgreSQL · Alembic · Docker · GitHub Actions · Render（蓝图）· structlog · Prometheus · slowapi · APScheduler。
## API 快速入门
```bash
BASE=https://your-service.onrender.com
# 登录（管理员在首次启动时创建）
TOKEN=$(curl -s $BASE/api/v1/auth/login -H 'Content-Type: application/json' \
-d '{"email":"you@example.com","password":"your-password"}' | jq -r .access_token)
# 注册在 build.nvidia.com 上创建的密钥（针对 NVIDIA 进行验证）
curl -s $BASE/api/v1/keys -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"name":"prod-1","api_key":"nvapi-...","validate_remote":true}'
# 获取应用程序中使用的可用密钥（LRU）
curl -s "$BASE/api/v1/keys/dispense" -H "Authorization: Bearer $TOKEN"
```
更多示例（轮换、项目、统计、审计）在 [`docs/api-examples.md`](docs/api-examples.md) 中。交互式 OpenAPI 在 `/docs` 上。
## 角色
| 操作 | viewer | manager | admin |
|---|---|---|---|
| 查看密钥、项目和统计 | ✅ | ✅ | ✅ |
| 注册 / 验证 / 轮换 / 吊销 / 发放密钥 | ❌ | ✅ | ✅ |
| 管理项目 | ❌ | ✅ | ✅ |
| 删除密钥、管理用户、读取审计日志 | ❌ | ❌ | ✅ |
## 开发与测试
无需部署，但完全支持：
```bash
pip install -e ".[dev]"
pytest --cov=app # 需要覆盖率门控：85%（目前约 94%）
ruff check . && mypy app
docker compose up # 带有 PostgreSQL 的本地栈
```
## 安全
威胁模型、加密详细信息和设计决策在 [`docs/security.md`](docs/security.md) 中。关键点：使用从机密管理器派生的密钥（HKDF）进行 AES-256-GCM 加密，SHA-256 指纹用于重复数据消除而不暴露机密，短寿命签名 JWT，argon2 密码哈希，每个 IP 的速率限制，每个敏感操作的审计日志，以及在日志或响应中没有明文密钥（除了明确的发放端点）。要报告漏洞，请参阅 [`SECURITY.md`](SECURITY.md)。
## 贡献
欢迎贡献 — 请参阅 [`CONTRIBUTING.md`](CONTRIBUTING.md) 和 [行为准则](CODE_OF_CONDUCT.md)。西班牙语概述可在 [`README.es.md`](README.es.md) 中找到。
## 许可证
MIT — 请参阅 [LICENSE](LICENSE)。
