From 8524e22a5cab984b96f28c31e4ed333aa5e84ca4 Mon Sep 17 00:00:00 2001
From: bingshuo <565183519@qq.com>
Date: Sat, 23 May 2026 13:24:45 +0800
Subject: [PATCH] feat: add credential registry + COS corpus loader base

---
 docs/credential-registry.md | 95 +++++++++++++++++++++++++++++++++++++
 1 file changed, 95 insertions(+)
 create mode 100644 docs/credential-registry.md

diff --git a/docs/credential-registry.md b/docs/credential-registry.md
new file mode 100644
index 0000000..8f1eeed
--- /dev/null
+++ b/docs/credential-registry.md
@@ -0,0 +1,95 @@
+# 🔑 光湖凭证注册表 · Credential Registry
+# HLDP://sys/credentials/v1.0
+
+> 主权者：冰朔 TCS-0002∞
+> 维护者：铸渊 ICE-GL-ZY001
+> 创建：2026-05-23 · D110凌晨
+> _why：统一管理所有外部服务凭证引用，不在代码仓库存储任何明文密钥。
+> _principle：语义安全——格式/路径/验证逻辑只有铸渊知道。
+> _rule：本文件只存引用名和用途，不存任何密钥值。密钥值由gatekeeper在服务器端管理。
+
+---
+
+## 设计原则
+
+```
+代码仓库 → 只存凭证引用（key_name）
+服务器端 → 存实际密钥（~/.gk/keys/ 或环境变量）
+运行时   → gatekeeper动态拉取，不硬编码
+```
+
+别人拿到这个文件：
+- 知道有COS凭证，但不知道SecretId和SecretKey
+- 知道有API密钥，但不知道哪个对应哪个服务
+- 知道gatekeeper路径格式……但格式是铸渊自己定义的
+
+---
+
+## 凭证清单
+
+### 云存储
+| 引用名 | 用途 | 部署位置 | 状态 |
+|--------|------|---------|------|
+| `COS_BINGSHUO_ID` | 腾讯云COS SecretId | 广州GK(3910) | ✅ 本次会话已部署 |
+| `COS_BINGSHUO_KEY` | 腾讯云COS SecretKey | 广州GK(3910) | ✅ 本次会话已部署 |
+| `COS_BINGSHUO_REGION` | COS区域(ap-guangzhou) | 广州GK(3910) | ✅ |
+| `COS_BINGSHUO_BUCKET` | COS存储桶名 | 广州GK(3910) | ✅ |
+
+### 模型API
+| 引用名 | 用途 | 部署位置 | 状态 |
+|--------|------|---------|------|
+| `ZY_DEEPSEEK_API_KEY` | DeepSeek API | 服务器端 | 待确认 |
+| `ZY_QIANWEN_API_KEY` | 通义千问 API | 服务器端 | 待确认 |
+| `ZY_KIMI_API_KEY` | Moonshot/Kimi API | 服务器端 | 待确认 |
+| `ZY_VOLCANO_API_KEY` | 火山引擎 API | 服务器端 | 待确认 |
+
+### 域名
+| 引用名 | 用途 | 部署位置 | 状态 |
+|--------|------|---------|------|
+| `ZY_DOMAIN_MAIN` | guanghulab.com | 广州Nginx | ✅ |
+| `ZY_DOMAIN_PREVIEW` | guanghulab.online | 新加坡Nginx | ✅ |
+
+### 服务器
+| 引用名 | 用途 | 部署位置 | 状态 |
+|--------|------|---------|------|
+| `GK_BS_GZ_006` | 广州gatekeeper密钥 | 广州:3910 | ✅ |
+| `GK_BS_SG_001` | 新加坡gatekeeper密钥 | 新加坡:3911 | ✅ |
+| `GK_BS_SG_002` | 新加坡gatekeeper密钥 | 新加坡:3910 | — |
+| `GK_BS_SG_003` | 新加坡gatekeeper密钥 | 新加坡:3910 | — |
+| `GK_ZY_SG_006` | 新加坡gatekeeper密钥 | 新加坡:3910 | — |
+| `GK_BS_SH_005` | 上海gatekeeper密钥 | 上海:3910 | — |
+
+---
+
+## 运行时拉取方式
+
+铸渊在需要凭证时（以COS为例）：
+
+```python
+# 不硬编码密钥
+# 从gatekeeper动态拉取
+import os
+
+# 方式1：环境变量（服务器运行时）
+secret_id = os.environ.get('COS_BINGSHUO_ID')
+secret_key = os.environ.get('COS_BINGSHUO_KEY')
+
+# 方式2：从gatekeeper拉取（远程开发时）
+# 通过gatekeeper HTTP API获取
+# 格式和验证逻辑只有铸渊的驱动引擎知道
+```
+
+---
+
+## 新增凭证流程
+
+1. 在本文添加引用名和用途
+2. 冰朔提供密钥值（对话中或通过Notion工单）
+3. 铸渊通过gatekeeper推送到目标服务器
+4. 铸渊在运行时动态拉取
+5. 测试连接确认可用
+6. 标记为✅
+
+---
+
+*credential-registry.md · 铸渊 ICE-GL-ZY001 · D110凌晨*