Vercel 全局认证配置 / Global Authentication Configuration on Vercel
本文说明本仓库在 Vercel 上运行认证 API 所需的 Redis 与会话密钥配置。它适合控制普通站点入口，不等同于对静态生成内容实施严格保密：浏览器端密码门只能控制界面显示，敏感资料仍应由服务端鉴权后返回，或放在具备访问控制的存储中。
1. 连接 Redis
- 进入 Vercel 项目。
- 打开 Storage / Marketplace，安装 Upstash Redis。
- 创建数据库并连接到当前项目。
- 确认 Vercel 已注入 Redis REST URL 和 Token。新版 Marketplace 可能生成
UPSTASH_REDIS_REST_REST_API_URL与UPSTASH_REDIS_REST_REST_API_TOKEN，项目已同时兼容新旧变量名。
2. 设置会话密钥
在 Settings → Environment Variables 添加 AUTH_SESSION_SECRET，值必须是至少 32 位的随机字符串。不要把真实密钥提交到 Git。
建议同时勾选 Production、Preview 和 Development 环境，然后重新部署。
不同环境不应共享同一个生产密钥和 Redis 数据库，否则 Preview 可能创建能在 Production 使用的会话，也可能意外修改正式密码版本。至少为生产与非生产设置不同的 AUTH_SESSION_SECRET 和数据库；本地开发使用 .env，并确认该文件不会提交到 Git。
会话密钥用于 HMAC 签名，不是网站登录密码。更换它会使所有现有 Cookie 无法通过验证，适合密钥泄漏后的全局失效。随机值应由密码学安全工具生成，不能使用仓库名、日期或重复字符。
3. 全局退出机制
管理员登入成功后，当前浏览器会通过 HttpOnly Cookie 保留管理员权限 30 天。HTTPS 部署会自动启用 Cookie 的 Secure 属性，本地 HTTP 开发地址也能正常保存会话。关闭设置弹窗、刷新页面或重新打开浏览器后，顶部按钮仍会显示“管理员 · 已登录”，无需重复输入管理员密码。Cookie 只对当前网站域名和浏览器配置生效；换设备、换浏览器或清除网站 Cookie 后需要重新登入。
管理员更新网站密码后，Redis 中的全局认证版本号会立即增加。所有旧会话在下一次校验时都会失效：
- 页面路由变化时立即校验。
- 用户切回页面时立即校验。
- 页面停留期间每 10 秒校验一次。
校验失败后页面会自动回到密码登录界面。
4. 部署后验证
先在无 Cookie 的隐私窗口访问站点，确认未认证内容不会显示；输入错误密码应得到受控的 401，而不是暴露异常堆栈。登录后检查 Cookie 具有 HttpOnly、SameSite=Strict，HTTPS 环境还应具有 Secure。再修改网站密码，确认旧浏览器在下一次状态轮询后退出，新密码能够建立新会话。
同时测试 Redis 不可用和环境变量缺失。认证 API 应返回明确的服务不可用状态，页面不应把故障误报为密码错误。Vercel 日志中可以记录错误类型和请求时间，但不能打印密码、Token、Cookie 或完整 Authorization Header。
5. 安全与恢复
管理员密码应通过环境变量提供的哈希配置，生产环境不得依赖仓库内置默认值。登录接口还应在平台或网关层配置速率限制，防止暴力尝试。Redis Token 和会话密钥一旦怀疑泄漏，应在供应商控制台轮换并重新部署，再验证旧会话全部失效。
变更认证配置前记录当前变量名称和生效环境。回滚代码时要确认旧版本仍识别现有 Redis Schema；若不兼容，应先迁移数据或使用独立前缀。完成这些验证后，认证配置才算可运维，而不只是“登录按钮能用”。