这页聚焦 玩家签到数据存在哪、管理员怎么迁移后端、怎么做校验与排障。

---

当前支持的存储后端

HNSignIn 现在支持两种玩家数据后端：

1. YAML（legacy / 迁移）

每名玩家一个文件：

plugins/HNSignIn/playerdata/<uuid>.yml

适合：

• 单服
• 测试服
• 希望人工排障时直接看文件
• 需要手工修一两名玩家状态

2. database（当前默认推荐）

通过 HNCore DatabaseManager 接入，当前支持：

• sqlite
• mysql

当前会维护这些表：

• <prefix>players
• <prefix>sign_records
• <prefix>claimed_total_rewards
• <prefix>claimed_weekly_template_rewards
• <prefix>claimed_monthly_template_rewards

适合：

• 更正式的线上环境
• 想集中管理数据
• 不希望玩家数据散落成大量 YAML 文件

---

YAML 单玩家文件里通常包含什么

1. 玩家基本信息

• player.uuid
• player.last-known-name

2. 每日签到记录

位于：

• records.<yyyy-MM-dd>.type
• records.<yyyy-MM-dd>.signed-at

其中 type 常见为：

• NORMAL
• MAKE_UP

3. 已领取的累计签到奖励

位于：

• claimed-total-rewards

4. 个人七日循环状态

位于：

• template-state.personal-cycle.progress
• template-state.personal-cycle.round

5. 模板奖励领取状态

位于：

• claimed-template-rewards.weekly
• claimed-template-rewards.monthly

---

database 后端里大致存什么

虽然 database 后端不再直接暴露给你单玩家 YAML 文件，但逻辑结构是一一对应的：

• players：最近玩家名、个人循环状态、更新时间
• sign_records：每日签到日期、签到类型、签到时间
• claimed_total_rewards：已领累签档位
• claimed_weekly_template_rewards：周模板奖励领取状态
• claimed_monthly_template_rewards：月模板奖励领取状态

所以从业务视角看：

• YAML 和 database 存的是同一套业务数据
• 区别只在于落地形式不同
• 当前推荐把 database 当正式后端，yaml 当 legacy 兼容与迁移通道

---

迁移前你应该先知道什么

1. 切换后端不会自动迁移历史数据

改了：

storage:
  type: database

并不代表旧的 playerdata/*.yml 会自动进入数据库。

2. 真正迁移前建议先预览

/hnsignin migrate-storage preview

它会同时告诉你：

• yaml -> database 预计会迁移多少
• database -> yaml 预计会迁移多少
• 目标侧已有多少玩家会被跳过
• 有多少非法 YAML 文件名或读失败项

3. 真正执行必须加 confirm

例如：

/hnsignin migrate-storage yaml-to-database confirm
/hnsignin migrate-storage database-to-yaml confirm

不加 confirm 不会真的写入，只会给你预览并提示正确命令。

---

存储迁移命令

预览

/hnsignin migrate-storage preview
/hnsignin migrate-storage preview overwrite

作用：

• 不做实际写入
• 同时预览两个方向
• overwrite 表示按覆盖模式估算结果

校验

/hnsignin migrate-storage validate

作用：

• 比较 YAML 与 database 两侧玩家数量
• 找出只存在于一侧的玩家
• 比较两侧公共玩家的摘要是否一致

当前摘要会比：

• 最近玩家名
• 总签到天数
• 已领累签奖励数量
• 周/月模板奖励条目数
• 个人循环进度与轮次

YAML -> database

/hnsignin migrate-storage yaml-to-database confirm
/hnsignin migrate-storage yaml-to-database overwrite confirm

含义：

• 不带 overwrite：目标 database 已有玩家则跳过
• 带 overwrite：用 YAML 数据覆盖目标 database 已有记录

database -> YAML

/hnsignin migrate-storage database-to-yaml confirm
/hnsignin migrate-storage database-to-yaml overwrite confirm

含义：

• 不带 overwrite：目标 YAML 已有玩家文件则跳过
• 带 overwrite：用 database 数据覆盖目标 YAML 文件

---

迁移与校验报告在哪里

预览、迁移、校验都会导出报告：

plugins/HNSignIn/migration-reports/

报告通常会包含：

• 动作类型
• overwrite 状态
• 源/目标后端描述
• 扫描统计
• 逐条明细
• 错误信息

这意味着：

• 迁移不是黑盒操作
• 事后能回看这次到底做了什么
• 排查失败记录时更容易定位到具体 UUID

---

迁移与校验时会看到什么进度

当数据量较大时，命令会输出阶段性进度，例如：

• 预览 yaml -> database: 30/100 (30%)
• 迁移 database -> yaml: 80/100 (80%)
• 校验公共玩家数据: 100/100 (100%)

所以如果玩家数据比较多，不要因为命令连续输出进度就误以为异常，这属于正常行为。

---

运维时最常看的几个问题

1. 玩家为什么今天不能签到

先看：

• query 里当前业务日是什么
• 玩家今天对应业务日是否已经有记录
• 当前时间是否还没过重置点

2. 玩家为什么不能补签

先看：

• 目标日期是否早于当前业务日
• 是否超出 window-days
• 是否被跨月限制挡住
• 是否命中了 conditions / limits / rules 中的拒绝条件
• 是否配置了 currency / item / warehouse requirement 且资源不足
• 对应软依赖（HNEconomy / HNWarehouse）是否可用

另外，当前 GUI 已经在入口层对“未来日期 / 不可补签日期”做了显式短路。也就是说：

• 未来日期不会再继续进入异步补签链路
• 明确不可补签的日期会直接在界面层拒绝

所以如果玩家反馈“点了没反应”，先不要只往后端查，也要先确认该日期当前是否本来就不可补签。

3. 奖励为什么没发

先分三层排查：

• 数据有没有写进去
• 模板状态有没有记录成已领
• 奖励投递是否进入了待重试状态
• 奖励动作本身能不能成功执行

如果是 library-item，还要额外排查：

• source 是否存在
• 来源当前是否可用
• key 是否有效

如果是 item-spec，还要额外排查：

• spec 结构是否符合 HNCore ItemSpec 语义
• identity / pdc 字段是否写对
• serial: auto 是否符合预期，生成后的物品是否真的被正确投递

---

推荐先用命令，不要先改数据

当前版本已经提供比较完整的维护命令：

查询

/hnsignin query <玩家>

现在 query 还会额外显示：

• 奖励投递总数
• 待重试奖励数量

重置模板状态

/hnsignin template-reset <玩家> all
/hnsignin template-reset <玩家> current-weekly
/hnsignin template-reset <玩家> current-monthly

手动补发模板奖励

/hnsignin template-grant <玩家> fixed-cycle 1
/hnsignin template-grant <玩家> final-reward final

说明：

• template-grant 现在会先登记奖励待发记录，再执行实际发奖
• 如果部分动作失败，失败记录会保留为待重试状态

手动重试奖励补偿

/hnsignin retry-rewards <玩家>

适合场景：

• 玩家状态已经写入，但奖励动作失败
• query 显示仍有待重试奖励
• 你想在不重置模板状态的前提下，只重跑奖励投递

此外，玩家再次打开签到 GUI 时，系统也会自动尝试补发未完成奖励。

迁移 / 校验

/hnsignin migrate-storage preview
/hnsignin migrate-storage validate

说明：

• 迁移与校验现在在后台异步执行
• 会持续回显进度百分比
• 不会把整段扫描/对比过程全部压在主线程里

如果这些命令能解决问题，优先走命令；只有在命令不够表达时，再考虑手改 YAML 或直接操作数据库。

---

什么时候适合手改 YAML

适合手改的情况通常是：

• 当前后端就是 YAML
• 玩家数据文件已经损坏
• 需要批量修一批历史玩家
• 你明确知道哪一个字段写错了
• 测试环境要构造特殊案例

不建议一上来就直接改：

• 当前业务周期领奖状态
• 个人七日循环状态
• 历史签到记录

因为这些字段一旦改错，会导致模板命中逻辑更难排查。

---

最稳的运维顺序

如果你准备把生产环境从 YAML 切到 database，推荐顺序：

1. 修改 storage.type
2. /hnsignin reload
3. /hnsignin status
4. /hnsignin migrate-storage preview
5. /hnsignin migrate-storage validate
6. /hnsignin migrate-storage yaml-to-database confirm
7. 再次 /hnsignin migrate-storage validate

如果你要回滚回 YAML，也建议：

1. /hnsignin migrate-storage preview
2. /hnsignin migrate-storage database-to-yaml confirm
3. /hnsignin migrate-storage validate

这样最不容易把问题越修越乱。 ��中逻辑更难排查。

---

最稳的运维顺序

如果你准备把生产环境从 YAML 切到 database，推荐顺序：

1. 修改 storage.type
2. /hnsignin reload
3. /hnsignin status
4. /hnsignin migrate-storage preview
5. /hnsignin migrate-storage validate
6. /hnsignin migrate-storage yaml-to-database confirm
7. 再次 /hnsignin migrate-storage validate

如果你要回滚回 YAML，也建议：

1. /hnsignin migrate-storage preview
2. /hnsignin migrate-storage database-to-yaml confirm
3. /hnsignin migrate-storage validate

这样最不容易把问题越修越乱。