数据目录与迁移

Hoshimi 的所有状态都在一个数据目录里：配置文件、记录用量和对话的数据库，以及少数几个给人或其他程序读的文件。搬家、备份或重置时只需要处理这一个文件夹。

数据目录在哪里复制锚点链接

设置环境变量 HOSHIMI_DATA_DIR 可以换到任意位置（支持 ~，会被解析为绝对路径）。服务器和所有命令都按这个变量找数据目录，所以想让 hoshimi config、hoshimi login 等命令操作同一份数据，就在运行它们的环境里设置同样的值：

export HOSHIMI_DATA_DIR=/srv/hoshimi
hoshimi config path          # /srv/hoshimi/config.json
hoshimi serve

$env:HOSHIMI_DATA_DIR = "D:\hoshimi"
hoshimi serve

查看正在使用的位置：

• hoshimi config path 打印配置文件路径，它所在的文件夹就是数据目录；
• hoshimi env 列出 Hoshimi 读取的环境变量和当前已设置的值；
• 网页界面的 设置 › 关于 显示 数据目录、配置文件 和 数据库；
• GET /api/v1/settings 返回 data_dir 和 config_path。

目录里有什么复制锚点链接

<数据目录>/
├── config.json                 设置和渠道账号
├── config.json.corrupt-<时间>   无法解析时保留下来的原文件副本
├── hoshimi.db                  数据库：用量、签到、探测结果、Playground 对话
├── hoshimi.db-wal / -shm       SQLite 的预写日志文件
├── server.json                 正在运行的服务器的地址、端口和进程号
├── eac-user.json               EAC 渠道的 GitHub 授权
├── oauth-installation-id       部分渠道浏览器登录使用的本机安装 id
├── catalog-cache/              各渠道最近一次成功拉取的模型目录
└── workspace/                  Playground 工具的默认工作目录

不是每个文件都会出现：它们在第一次用到时才创建。设计上，随流量增长的记录都放进数据库；需要人手查看、编辑或给其他程序读取的东西保持为普通文件。

数据库 hoshimi.db复制锚点链接

一个 SQLite 文件保存网关积累的所有记录：

用量统计大约每秒批量写入一次，服务器退出时再写一次；对话消息在发送时写入。每次启动时，上次中断在半路的回复会被标记为已停止，未发送的附件会被清理。

数据库使用 WAL 模式，并设置了 5 秒的忙等待，所以服务器运行时，命令行也可以同时读写同一个文件。

数据库结构的升级复制锚点链接

数据库结构按编号依次升级，版本号记在 SQLite 的 user_version 中。新版本的 Hoshimi 第一次打开旧数据库时自动完成升级，不需要手动操作。

如果数据库是被更新版本的 Hoshimi 用过的，旧版本启动时会警告：

… was last used by a newer Hoshimi (database schema N, this one knows M); what it recorded may not show correctly

此时旧版本仍可运行，但部分记录可能显示不正确。降级前先备份数据目录。

日志复制锚点链接

Hoshimi 不写日志文件，所有日志都输出到标准错误（stderr）。服务器开始监听后，标准输出会打印一行 SERVER_READY url=http://…，方便脚本获取实际地址。

HOSHIMI_LOG_LEVEL=DEBUG hoshimi serve      # 级别：DEBUG、INFO（默认）、WARNING、ERROR
hoshimi serve --debug                      # 同样打开调试日志
hoshimi serve --no-open 2>> hoshimi.log    # 需要日志文件时自己重定向

作为系统服务运行时，日志由服务管理器收集（如 journalctl），见安装。

从旧版本迁移复制锚点链接

hoshimi config path

hoshimi check

备份与重置复制锚点链接