前言¶

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 倉庫