配置
配置
配置首先分成持久化目录、安装器管理的数据库连接和后台站点设置。不要把数据库连接写入旧环境变量后期待绕过安装流程。
目录与主密钥
| 变量 | 当前行为 |
|---|---|
APP_DATA_PATH | 应用配置与本地数据库根目录；源码默认工作目录下的 data，容器使用 /app/data。 |
UPLOAD_STORAGE_PATH | 托管上传目录；源码默认工作目录下的 data/uploads，容器使用 /app/data/uploads。 |
BACKUP_STORAGE_PATH | 完整备份独立目录；默认 ${APP_DATA_PATH}/backups。 |
ENCRYPTION_KEY | 优先作为稳定主密钥；未提供时生成并持久化到应用配置目录的 master.key。 |
BACKUP_DATABASE_TRANSACTION_TIMEOUT_MS | 正整数毫秒，默认 3,600,000；无效值回退默认值，最大 2,147,483,647。只作用于数据库备份/恢复事务。 |
APP_DATA_PATH 与 UPLOAD_STORAGE_PATH 独立解析。只改变前者不会自动把上传目录迁入新根目录，应显式设置两者。例如，在仓库根目录本地启动：
APP_DATA_PATH=./data UPLOAD_STORAGE_PATH=./data/uploads npm run dev
数据库连接配置保存在 config/database.enc，以 AES-256-GCM 加密并使用原子文件写入。主密钥必须与加密配置一起长期保留；更换部署、挂载目录或容器时不要临时生成新密钥替换旧密钥，也不要在日志或聊天中输出密钥。
MySQL/PostgreSQL 的数据库目录与应用目录分别持久化。配置含凭据，生成的 Compose 文件按私有文件管理，部署程序使用 0600 文件权限和 0700 新目录权限。
数据库选择与安装状态
一个实例只使用一种主数据库。SQLite 面向单实例本地磁盘；MySQL 要求 8.0+、InnoDB，PostgreSQL 要求 14+。远程数据库的主机、端口、库名、账号、密码和 TLS 通过网页安装器配置。
安装状态依次为 UNCONFIGURED、CONFIGURING、SCHEMA_READY、INSTALLED；配置不能解密或已安装数据库不可用时进入维护流程，不开放重新安装。当前源码要求数据库修订 17，后续已提交迁移由启动流程执行。
DATABASE_URL 和旧 DB_* 变量不是应用运行时选择数据库的入口。Compose 使用受控 SLOTHVAULT_AUTO_BOOTSTRAP 及 SLOTHVAULT_BOOTSTRAP_* 参数完成首次引导；不要手工拼接不完整参数替代部署程序。已有配置不匹配或目标库非空时会停止，而不是覆盖原库。安装后不支持在线切换 provider；迁移到另一 provider 应经过备份、目标实例安装、恢复预检和验证。
Solana 与站点来源
| 变量 | 用途 |
|---|---|
SOLANA_RPC_URL | Mainnet 主 RPC 的环境回退值。 |
SOLANA_MAINNET_RPC_FALLBACK | Mainnet 备用 RPC 回退值。 |
SOLANA_DEVNET_RPC_URL | Devnet 主 RPC 的环境回退值。 |
SOLANA_DEVNET_RPC_FALLBACK | Devnet 备用 RPC 回退值。 |
NEXT_PUBLIC_SOLANA_RPC_URL | 浏览器 Wallet Adapter 的公开集群地址。 |
NEXT_PUBLIC_SITE_ORIGIN | 本站规范来源；参与 MCP 接入地址生成和本站绝对文件 URL 的识别。 |
后台 RPC 设置优先使用保存的节点配置，环境变量用于回退。NEXT_PUBLIC_* 内容面向浏览器，不放带私密凭据的地址，并在构建与运行配置中保持一致。MCP 地址生成不会根据任意 Host 或 Forwarded 头推导凭据发送目标。
品牌、首页、语言、主题、备案及权限设置由各自后台页面管理。权限配置属于业务数据，不通过文档生成顺带变更。
备份兼容性与反向代理
当前完整包格式为 2、备份业务数据版本为 2.16.0，显式兼容 2.13.0、2.14.0、2.15.0。应用版本 2.6.10、数据库修订 17 与备份数据版本不是同一种编号。普通文件上传上限为 10 MiB、头像为 2 MiB；完整备份采用独立的 8 MiB 分片上传流程，不能把普通文件上限套到完整备份总量。
完整备份实际容量仍受磁盘和系统资源限制。恢复会改写当前业务数据，必须先完成预检和恢复前保护备份；敏感账号、密码哈希和卡密哈希随包保存，应限制下载与存储权限。
官方部署程序支持标准系统级 Nginx，或显式指定的官方 nginx 容器；不接管宝塔及其他面板托管 Nginx。宿主机反代使用应用宿主端口，容器反代必须共享应用网络，不能把容器自己的 127.0.0.1 当作宿主机。分片上传经过代理时，单次请求体限制应允许至少 8 MiB，并为请求开销留余量。