dsh-credentials-mysql：DeepSeek Harness 的 MySQL 憑證庫

前言¶

DeepSeek Harness（DSH）採用插件化架構，憑證管理是其中關鍵的一環。傳統的本地文件存儲（dsh-credentials-local）適合單機運行，但在需要多實例共享憑證的場景下存在侷限。dsh-credentials-mysql 插件旨在解決這一問題，它將憑證存儲從本地文件遷移至 MySQL 數據庫，支持多進程共享與事務一致性，是構建分佈式 DSH 部署時的標準憑證組件。

插件介紹¶

這是一個基於 MySQL 的後端憑證庫插件，屬於 admin-security 分類。插件維護者爲 sandersyao，採用 MIT 許可證。它實現了 DSH 的 CredentialProvider 接口，提供與本地文件存儲行爲一致的憑證讀取、設置與清除能力，同時增加了數據庫持久化、共享訪問和字段級加密功能。

核心功能¶

MySQL 持久化存儲：將憑證數據持久化到數據庫，支持多進程併發訪問。
AES-256-GCM 字段級加密：支持對敏感字段（如憑證值、Payload）進行加密存儲，密鑰通過 SHA-256 派生且不存儲在數據庫中。
共享數據庫部署：可與 dsh-workspace-bootstrap、dsh-storage-mysql 等插件配合，使用同一個 MySQL 實例作爲共享後端。
事務一致性：利用 InnoDB 事務和行鎖（SELECT ... FOR UPDATE）保證併發寫入時的安全，支持死鎖重試。
連接池配置：內置連接池機制，默認大小爲 10，可配置。

安裝與啓用¶

通過 npm 安裝依賴後，在初始化代碼中註冊插件。

import { MysqlCredentialProvider } from '@sandersyao/dsh-credentials-mysql'

await ctx.plugin(MysqlCredentialProvider, {
  connection: { tablePrefix: process.env.CREDENTIALS_TABLE_PREFIX },
})

註冊後，ctx.credentials 將由 MySQL 提供者接管。

配置說明¶

憑證庫的連接信息與加密配置通過環境變量注入，插件優先讀取 CREDENTIALS_* 開頭的變量，若未設置則回退到 MYSQL_* 變量。

必填配置：
- CREDENTIALS_HOST：MySQL 主機（默認 127.0.0.1）。
- CREDENTIALS_PORT：MySQL 端口（默認 3306）。
- CREDENTIALS_USER：數據庫用戶名。
- CREDENTIALS_PASSWORD：數據庫密碼。
- CREDENTIALS_DATABASE：目標數據庫名。
- CREDENTIALS_TABLE_PREFIX：表前綴，用於區分不同插件的表，需符合正則 ^[A-Za-z0-9_]+$。

可選配置：
- CREDENTIALS_ENCRYPTION_KEY：加密密鑰，爲空字符串時明文存儲（啓動會警告）。32 字節十六進制字符串或其他字符串均可。
- CREDENTIALS_POOL_SIZE：連接池大小（默認 10）。
- CREDENTIALS_SCHEMA_AUTO_MIGRATE：是否在啓動時自動遷移表結構（默認 true）。
- CREDENTIALS_SSL_REQUIRED：TLS 強制要求（當前爲預留狀態）。

存儲結構與併發¶

插件在數據庫中創建三個表，均使用 CREDENTIALS_TABLE_PREFIX 作爲前綴：
- ${prefix}credential_refs：存儲引用（ref_name 和 value）。
- ${prefix}credential_records：存儲記錄（rec_key, kind, payload）。
- ${prefix}credential_meta：存儲 schema 版本信息。

併發處理：
modifyRecord 操作在多進程環境下是互斥的，通過 SELECT ... FOR UPDATE 實現行級鎖和事務隔離，確保併發刷新 Token 時的數據安全。寫入操作具有原子性，InnoDB 保證已提交的數據不會丟失。

注意事項¶

無熱發佈：插件不監聽文件變化，直接在 MySQL 中修改數據不會實時更新到運行中的進程（需等待下次重新解析）。
無自動遷移：不支持從本地 .credentials.yaml 文件自動遷移數據到 MySQL。
TLS 預留：CREDENTIALS_SSL_REQUIRED 目前爲預留功能，暫未啓用。
依賴版本：插件依賴 DSH 生態的 ^0.1.5-rc.1 版本 peerDependencies，安裝前需確認環境兼容。

總結¶

dsh-credentials-mysql 提供了標準化的 MySQL 憑證存儲方案，適合需要多節點協作的 DeepSeek Harness 部署。通過配置連接池和加密參數，可以在保證安全性的同時獲得良好的讀寫性能。更多細節可查閱插件目錄或源碼倉庫。