🔒 安全：两轮审计修复 14 项（本次升级的核心理由）#

本轮按「SSO 信任锚 → 权限模型 → SSRF → DoS → 缓存」逐层排查，重点修复：

如果你正在公网运行旧版本（v3.5.x / v4.5.5 及更早），以上漏洞意味着：任何注册用户都可能把自己变成超管，任何访客都可能消耗你的服务器资源、污染你的 CDN 缓存、或者锁死管理员账号。这不是理论风险，是可直接复现的攻击路径。

🐛 修复：保存源文件名仍追加随机后缀（Issue #45）#

感谢 @dasima4396 反馈。开启「保存源文件名」后，上传 风景.jpg 会得到 风景_fghx-x45djh-566.jpg —— 文件名末尾被无条件追加了一长串随机字符；关闭开关后的自动命名也带有同样的后缀。

本版本的行为：

• 开启「保存源文件名」后不再追加随机后缀，风景.jpg 上传后就是 风景.webp（后缀按实际格式修正）；
• 可读字符（中文、空格、短横线等）原样保留，不可读字符折叠为单个 -，同时防御路径逃逸与 Windows 保留名；
• 重名自动编号：风景.webp → 风景-2.webp → 风景-3.webp……探测占用失败时回退随机命名，绝不覆盖已有图片；
• 关闭开关时保持原有「模板 + 随机串」命名逻辑不变。

✨ 新增：用户上传配额#

每个用户的可上传总量支持三档语义：

• 管理员与超级管理员不参与配额；
• 配额判定以落盘后的真实大小为准（PNG 转码为更小的 WebP 后不会被误判超限）；
• 用户卡片实时显示进度条（<70% 主色 / 70–90% 琥珀 / ≥90% 红色）。

⚡ 新增：转码结果缓存#

同一张图 + 同一组水印参数，输出恒定，不再重复计算。实测一张 4335×2520 的图：冷转码 0.626s，命中缓存 0.0138s（快 45 倍），且命中时跳过远端存储回源。缓存键覆盖全部水印参数，修改任何参数都会生成新键；改动水印设置时主动失效，避免「改了没生效」的调试困惑。

🛡️ 新增：反代信任配置 TRUSTED_PROXIES（反代用户必读）#

v4.0.0 起默认不信任任何代理头：X-Forwarded-For 仅当请求来源在 TRUSTED_PROXIES 列表内才被采信。这是「安全默认」的取舍——不配置时，反代部署下所有访客会共用反代 IP 的限流预算（限流会变得不准，但不会危及安全）。

⚠️ 配置了非法条目（不是合法 IP/CIDR）时应用会拒绝启动，而非静默忽略——避免限流在毫不知情的情况下失效。

🔧 修复：Turnstile 配置不完整时的降级#

「人机验证方式」选了 Turnstile 但密钥没填全时，此前验证逻辑会回退到本地 POW，但 CSP 头仍按 Turnstile 收紧，导致 POW 组件的 WebAssembly 被浏览器拒绝、验证永远无法完成。现在降级决策统一收敛到一处，CSP 与验证行为保持一致；设置页会明确提示「缺少哪些配置」。

🎨 界面与体验#

系统设置页

• 布局整页重写：页签栏吸顶（滚动时始终可见）、统计信息并入页签栏右侧、表单/说明栅格再平衡（输入框不再比说明文字还窄）、各面板内部改两列布局（窄屏自动堆叠）
• 页签选中态对比度修正：深色模式 1.41 → 7.27（WCAG AAA），浅色 5.83
• 页签同步到 URL（?tab=xxx）：刷新、前进/后退都能回到原页签，直达链接自动滚动到选中项
• 新增「系统」页签：显示当前版本号、检查更新（服务端缓存 5 分钟查询 GitHub，避免浏览器限流），有新版本时显示更新日志与跳转链接
• 版本信息从账户设置移至系统设置；侧栏与用户菜单顺序统一为「账户设置 → 系统设置」
• 移除初春 POW 在线验证服务（cha.eta.im）：验证方式收敛为「无验证 / Turnstile / 本地 POW（cap-pow）」三选一，旧库里的 pow 配置自动回落，相关 CSP 白名单与前端死代码全部清理
• Turnstile 配置不完整自动回退本地 POW，设置页明确提示缺哪些配置，修复 CSP 不放行 wasm 导致验证永远无法通过的 Bug
• 安全开关（人机验证与访问控制）上移为独立面板，Referer 白名单迁入安全页签

账户设置页

• 修复 7 个无定义的「幽灵类名」；登录会话与登录历史 ≥1280px 并排（整页高度 ~1400 → 728）
• 登录会话：新增「剩余 N 天/小时/分钟」（<24h 琥珀提醒）、当前会话高亮、无其他会话时禁用「退出其他会话」
• 登录历史：改为时间线样式（竖线 + 圆点，最新一条高亮 +「最近一次」徽章）
• 修改密码：新密码/确认并排，按钮初始禁用（有改动且填了当前密码才可提交）

登录页（未登录状态）

• 未登录时不渲染侧边栏：未登录状态下没有任何可导航页面，侧边栏整块不再出现（登录后恢复）；内容区不再为不存在的侧栏让位
• 登录卡片与顶栏导航的布局、样式微调

其他

• 主题切换圆形揭示动画（View Transitions API），用户菜单缓入缓出
• API Token 按钮分离：生成/重新生成/复制各自独立，修复输入框右侧 112px 死区
• 标签管理页重构：修复添加/修改/删除无响应的问题（引用未定义的组件）+ 按 id 定位防误删
• 图库新增瀑布流视图、筛选与详情弹窗；最近上传卡片重排（文件名在元信息上方）
• 通知 Toast（message.js）布局自适应：PC 75px 边距、移动端 16px 对称边距、自动让出导航栏高度、悬停暂停自动关闭
• 表单校验错误信息中文化（如「密码不能少于 8 位」「用户名 3-20 个字符」）
• 数据统计页重做、全站去除 :focus-visible 黑框、搜索框与输入控件样式统一（.input-modern）

🧱 代码重构#

• controllers 按业务域拆分为 auth / images / storage / system / users / shared 六个子包，循环依赖清零
• 水印/验证策略/外部认证配置等纯逻辑下沉到独立工具包

升级指南#

本次升级无破坏性变更，可直接覆盖升级。但仍建议按以下顺序操作：

1. 备份 ./data 卷（数据库 + data/.config_secret + data/.session_secret + data/.initial_admin_password 都在里面，丢失后已加密的存储凭据无法恢复）；
2. 备份数据库（如使用外部 MySQL / PostgreSQL，单独做一次 dump）；
3. 覆盖升级二进制或拉取新镜像：

1
docker pull onexru/oneimg-oneimg:v4.0.0
2
# 或
3
docker pull onexru/oneimg-oneimg:latest
4
docker compose up -d

4. 反向代理部署的用户，配置 TRUSTED_PROXIES（Docker 内反代用 172.16.0.0/12，本机反代用 127.0.0.1），否则所有访客会共用反代 IP 的限流预算；
5. 确认 APP_URL 已设置为实际访问地址（图片外链基址取自该值）；
6. 升级后进「系统设置 → 系统」页签确认版本号为 v4.0.0。

从 v3.5.5 及更早版本升级时，若 .env 里还留着 DEFAULT_PASS=123456，请删除该行或改成强密码（初始管理员密码从 v3.5.6 起已改为随机生成，写入 data/.initial_admin_password）。

下载与部署#

• 二进制包为单文件静态链接程序（webp / sqlite3 由 cgo 内嵌编译），无运行时依赖。
• Docker Hub 支持 linux/amd64 与 linux/arm64 双架构。

最后再说一次：为了你的数据安全和服务器安全，请务必尽快升级到 v4.0.0。 如果升级过程中遇到问题，欢迎在 GitHub 提 Issue 反馈。