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 部署。通过配置连接池和加密参数，可以在保证安全性的同时获得良好的读写性能。更多细节可查阅插件目录或源码仓库。