Configuration

配置参考

部署操作见部署指南，界面设置见使用指南。

三类配置分别放在哪里

类型	保存位置	例子
Cloudflare 部署配置	wrangler.toml / Worker 设置	Worker 名称、KV、Durable Object、域名、Cron
运行时 Secrets 和变量	Secrets 存于 Worker 的 Variables and Secrets；普通变量写在 wrangler.toml 的 [vars]	ENCRYPTION_KEY、OAuth 客户端凭据、ENVIRONMENT
应用偏好	应用设置界面；服务端偏好存于 KV 的 settings 等记录，视图等本机偏好存于当前浏览器	登录有效期、备份保留数、导出格式、语言、默认显示方式

请使用 Cloudflare Secret 保存密钥和密码，不要把真实值写进 Git 仓库。Wrangler 的环境变量并不等同于应用运行时配置；例如 CLOUDFLARE_ENV 选择部署目标，不是管理密码。

存储绑定

SECRETS_KV

必需的 Workers KV 绑定，名称大小写必须一致。账户主数据、管理密码哈希、服务器备份、应用设置及远程存储配置等都保存于此。ENCRYPTION_KEY 则保存在 Cloudflare Secrets 中。

[[kv_namespaces]]
binding = "SECRETS_KV"
# 已有部署可显式填写自己的 id；首次部署可以留给部署流程创建。

已知 ID 时添加 id = "自己的 KV ID"。不要写空字符串；部署脚本会视为配置错误。一个目标环境必须且只能声明一个名为 SECRETS_KV 的绑定。

SECRETS_STORE

标准配置声明以下绑定及初始迁移：

[[durable_objects.bindings]]
name = "SECRETS_STORE"
class_name = "SecretsStore"

[[migrations]]
tag = "v1"
new_sqlite_classes = ["SecretsStore"]

它让列表读取、账户修改、HOTP 计数器推进、备份和恢复等账户操作经过同一个 Durable Object，按顺序执行。SQLite 存储后端支持 Workers 免费计划，具体额度以 Cloudflare 账户为准。

DO 保存账户和计数器的最新写入副本，每次写入也同步到 KV。主数据仍完整保存在 KV，以兼容旧版本。它不把所有应用设置、登录限流或 OAuth 配置都变成强一致存储。

没有绑定时应用退回到 Worker 实例内的处理队列，不能提供跨实例的并发保护。已经配置绑定但 DO 暂时不可用时，部分读取可回退到 KV；修改可能返回 503，表示无法确认是否保存。此时先刷新核对状态，再决定重试。

迁移标签属于该 Worker 的历史，后续不要随意删改。跨 v1.11.0 的回滚步骤见升级与回滚。

运行时 Secrets 和变量

名称	是否必需	用途与建议
ENCRYPTION_KEY	可选，强烈推荐	Base64 编码的 32 字节随机值，用于 AES-GCM 256 位加密。作为 Secret 保存
ONEDRIVE_CLIENT_ID	使用 OneDrive 时	Microsoft Entra 应用 ID
ONEDRIVE_CLIENT_SECRET	使用 OneDrive 时	Microsoft 应用客户端密钥，作为 Secret 保存
GOOGLE_DRIVE_CLIENT_ID	使用 Google Drive 时	Google OAuth 客户端 ID
GOOGLE_DRIVE_CLIENT_SECRET	使用 Google Drive 时	Google OAuth 客户端密钥，作为 Secret 保存
OAUTH_REDIRECT_BASE_URL	OAuth 按需配置	公开访问基准地址，例如 https://2fa.example.com；自定义域名推荐明确设置
ENVIRONMENT	标准配置已提供	顶层为 production，开发为 development；影响日志和静态资源缓存策略
SW_VERSION	标准配置已提供	Service Worker 缓存版本，由部署脚本注入；不是应用发布版本号
LOG_LEVEL	可选	DEBUG、INFO、WARN、ERROR 或 FATAL。生产默认 INFO，开发默认 DEBUG
LOG_REMOTE_ENDPOINT	可选	配置后将结构化日志以 JSON POST 到指定地址；默认不发送远程日志。仅填写自己信任的日志接收端

OAUTH_REDIRECT_BASE_URL、LOG_LEVEL、LOG_REMOTE_ENDPOINT 这类普通变量请写进 wrangler.toml 的 [vars]（开发环境为 [env.development.vars]），或作为 Secret 添加。项目没有启用 keep_vars，只在 Dashboard 添加的文本变量会在下一次部署时被移除；Secret 不受影响。

WebDAV、S3 的地址和凭据在应用设置界面配置，不需要新增同名 Worker 环境变量。远程存储的详细申请、回调和授权步骤见远程存储。

ACCESS_TOKEN 是否需要设置

应用不读取 env.ACCESS_TOKEN。 它既不是必填部署项，也不能作为固定 API 密钥登录。旧示例或历史配置中即使保留此变量，也不会参与认证。

管理密码在首次设置页面创建，其哈希保存在 user_password。登录后的 JWT 使用该哈希签名，服务端接受登录 Cookie，或 Authorization: Bearer <登录获得的 JWT>。无需手动提供 JWT_SECRET。接口调用见 API 参考。

密钥和密码的区别

值	作用	丢失或变更后的影响
管理密码	登录应用	可以按常见问题重置；修改后旧登录令牌失效
ENCRYPTION_KEY	解密账户、加密备份及相应凭据	丢失原值无法解密已有密文；重置管理密码无帮助
服务商 2FA 密钥	生成某个账户的验证码	属于被管理的数据；拥有它就能生成对应验证码

配置 ENCRYPTION_KEY 后仍能读取旧明文账户；下一次保存账户时主文档才写成密文。历史备份及未重存的其他记录不会自动全部转换。移除密钥也不会解密已加密记录，系统会要求恢复原密钥。计划更换密钥前，应先用旧密钥导出并验证可恢复数据，同时保留旧密钥以读取旧备份，详见安全说明。

环境配置示例

完整配置以仓库的 wrangler.toml 为基线。下列片段仅展示账户库和开发环境需要调整或保留的项；请修改已有配置中的对应块，不要将片段当作完整配置覆盖文件，也不要重复添加同名块。已有部署须保留原 Worker 名称、生产 KV ID 和完整迁移历史。

compatibility_date 控制 Workers 运行时的兼容行为，应沿用仓库配置中的值；它不是部署日期，不要随部署改成当天日期。

[[kv_namespaces]]
binding = "SECRETS_KV"
id = "替换为自己的生产 KV ID"

[env.development]
name = "2fa-dev"
routes = []

[[env.development.kv_namespaces]]
binding = "SECRETS_KV"
id = "替换为独立的开发 KV ID"

[[env.development.durable_objects.bindings]]
name = "SECRETS_STORE"
class_name = "SecretsStore"

[env.development.vars]
ENVIRONMENT = "development"
SW_VERSION = "v1"

开发 Worker 名称和 KV 必须独立于生产环境；不要把生产 KV ID 填入开发绑定。routes = [] 防止开发环境继承生产路由，也可以改为独立测试域名。首次部署尚无 KV ID 时，可以保留无 ID 的绑定声明，让部署流程创建资源。

kv_namespaces、Durable Object 绑定、vars 和 Secrets 不会从顶层配置继承，需按环境独立声明或设置；没有自己的迁移列表时会继承顶层迁移。请保留仓库配置中的生产绑定及变量，并合并上游新增项。

npx wrangler secret put ENCRYPTION_KEY --env development
npm run deploy:dev

本地开发使用 npm run dev。需要本地 Secret 时，可使用仓库已忽略的 .dev.vars，例如：

ENCRYPTION_KEY=只用于本地测试的Base64密钥

Wrangler 会优先读取环境专用文件（如 .dev.vars.development），否则使用 .dev.vars；专用文件需自行加入 Git 忽略规则，避免提交本地凭据。

不要把生产 Secret 或真实账户数据复制到开发环境。默认本地 Wrangler 使用本地模拟存储；不要为了排错随意切换为连接生产资源的远程开发。

部署脚本的目标环境由 --env 优先选择，其次是进程变量 CLOUDFLARE_ENV；均未指定时部署顶层配置。如果命令似乎部署到错误环境，先检查这两处及 Cloudflare Builds 的目标 Worker。

定时任务

标准配置：

[triggers]
crons = ["0 16 * * *"]

Cloudflare Cron 使用 UTC，该表达式对应每天北京时间 00:00。另如 0 */6 * * * 表示 UTC 每 6 小时执行。修改后需重新部署。

Cron 根据数据哈希检查变化；没有账户、数据未变化或已有同批数据备份时不生成重复备份。账户修改也可触发事件备份，因此定时任务并非唯一备份入口。

绑定 SECRETS_STORE 时，定时任务还会清理不再被账户使用的 HOTP 计数器记录。它与是否需要新建备份分开执行。备份保留数按应用设置清理，默认 100，并不是固定不可调整。

应用设置的默认值

设置	默认	服务端接受范围
登录有效期 jwtExpiryDays	30 天	1～365 天
备份保留数量 maxBackups	100	0～1000 的整数；0 表示不限制
默认导出格式 defaultExportFormat	json	txt、json、csv、html
语言 language	auto	自动或项目支持的语言代码

默认导出格式也用于新的服务器备份。修改格式不改写已有文件。

“默认显示方式”是当前浏览器的本地偏好，保存在 localStorage 的 2fa-default-view-mode，不属于上表的服务端设置。默认值 remember 表示记住上次选择，grouped 和 flat 分别固定为智能聚合、全部平铺。修改后立即应用，固定方式下的主页菜单切换仅临时生效；刷新或重新打开时恢复固定方式。其他浏览器和设备需分别设置。主题、排序、离线行为等前端偏好的具体操作见使用指南和 PWA。

支持的语言

应用设置中的 language 可设为 auto（跟随浏览器），或以下语言代码。通过 API 的 X-Language 请求头或 lang 查询参数指定响应语言时，可使用表中的代码，例如 X-Language: en 或 ?lang=zh-TW。

auto 用于界面语言偏好，请勿用它指定 API 响应语言；API 会将显式传入的 auto 视为不支持的语言并回退到英语。

语言代码	语言
zh-CN	简体中文
zh-TW	繁体中文
en	英语
ja	日语
ko	韩语
de	德语
fr	法语
es	西班牙语
pt-BR	巴西葡萄牙语
it	意大利语
ru	俄语
tr	土耳其语
id	印度尼西亚语
vi	越南语
th	泰语

语言列表依据：共享语言注册表。请求语言的优先级与回退规则见 API 参考。

CORS 与自定义域名

普通 API 的 CORS 允许列表按请求 Host 生成，包含 https://<Host> 和 http://<Host>；本地 localhost / 127.0.0.1 还兼容不同开发端口。无需设置 CORS_ORIGIN 一类变量。自定义域名推荐通过 Cloudflare 原生路由绑定；代理若改写 Host 或来源，可能使浏览器跨域访问失败。CORS 不代替登录认证，具体响应规则见 API 参考。浏览器扩展有独立的授权流程，见浏览器扩展。

依据：标准配置 · 认证实现 · 加密实现 · 设置校验 · 存储协调。