前言¶

DeepSeek Harness (DSH) 的存储中心 (ctx.storage) 默认依赖 JSON 文件。对于需要持久化、崩溃恢复或跨进程可见性的场景，文件存储往往不是最佳选择。@sandersyao/dsh-storage-mysql 提供了替代方案，将存储后端迁移至 MySQL 数据库。

插件介绍¶

这是一款由 sandersyao 维护的 DeepSeek Harness 存储插件。它的核心定位是 @deepseek-ai/dsh-storage-json 的替代品，通过注册 MySQL 后端，将 KV 存储单元持久化到 InnoDB 表中，满足 ACID、崩溃安全及多进程可见的需求。

核心功能¶

1. 后端替换：作为插件加载后，会在 ctx.storage.backend 上注册名为 mysql 的后端。
2. KV 接口：暴露 kv facet，提供标准的读写操作。
3. 数据持久化：利用 MySQL InnoDB 引擎实现 ACID 事务，写入即持久化，支持崩溃恢复，多进程间共享数据。
4. 分布式部署组件：它是分布式 DSH 部署四件套中的一员，需配合 dsh-credentials-mysql、dsh-session-persistence-mysql 和 dsh-workspace-bootstrap 使用。

安装与启用¶

安装包名为 @sandersyao/dsh-storage-mysql。

代码集成¶

在 DSH 插件入口引入并注册：

import { apply, Config, inject, name } from '@sandersyao/dsh-storage-mysql'

ctx.plugin(
  { apply, Config, inject, name },
  { connection: { tablePrefix: 'dsh_storage_' } }
)

配置存储域¶

在配置文件中将 storage-domain 的 backend 指向 mysql：

{ backend: 'mysql' }

集成方式¶

该插件提供了 cordis.patch.yml。最简单的路径是通过 bundle patch 引入，它会保持默认的 storage-json 后端可用，同时将 storage-domain.backend 指向 mysql。

配置说明¶

插件不直接在代码中硬编码凭证，而是从环境变量或 .env 文件读取。

环境变量¶

插件优先读取 STORAGE_* 开头的变量，若未设置则回退到 MYSQL_*。

• STORAGE_HOST / MYSQL_HOST: 默认 127.0.0.1
• STORAGE_PORT / MYSQL_PORT: 默认 3306
• STORAGE_USER / MYSQL_USER: 必填，使用最小权限用户
• STORAGE_PASSWORD / MYSQL_PASSWORD: 必填
• STORAGE_DATABASE / MYSQL_DATABASE: 必填，目标数据库名
• STORAGE_TABLE_PREFIX / MYSQL_TABLE_PREFIX: 必填，表前缀（仅允许字母数字下划线），需确保与 session/credentials 插件前缀不冲突
• STORAGE_SSL_REQUIRED / MYSQL_SSL_REQUIRED: 默认 false
• STORAGE_POOL_SIZE / MYSQL_POOL_SIZE: 默认 10
• STORAGE_SCHEMA_AUTO_MIGRATE / MYSQL_SCHEMA_AUTO_MIGRATE: 默认 true，启动时自动迁移 schema

存储结构与安全¶

表结构¶

插件会在指定前缀下创建三张表：
* Pstorage_units: 存储单元定义及版本信息。
* Pstorage_records: 存储 (unit_name, table_name, record_key) 对应的 JSON 值。
* Pstorage_meta: 记录当前应用的 Schema 版本。

安全机制¶

• 参数绑定：unit_name、table_name、record_key 始终作为参数绑定（而非 SQL 标识符），防止 SQL 注入。
• 凭证隔离：凭证永不出现在代码或配置文件中。

注意事项¶

• 适用场景：适合需要跨进程共享状态或强一致性的分布式 DSH 部署。
• 许可证：MIT。
• 生态说明：此插件属于社区目录收录项目，与 DeepSeek 或幻方无官方从属关系。

结语¶

@sandersyao/dsh-storage-mysql 为 DSH 提供了一个成熟的 MySQL 存储后端，通过 ACID 保证数据安全，通过参数绑定保证运行安全。对于追求稳定性和分布式能力的部署，它是一个可靠的选择。

查看目录页
GitHub 仓库