企业官网建设流程全解析

Obsidian Arc 是一款自托管（self-hosted）AI 平台，内置 Go 服务端、多服务商路由、用量追踪和管理控制台。本文将给你一份完整的 Obsidian Arc 安全加固清单，覆盖 TOTP 两步验证、Turnstile 人机验证、PoW 工作量证明和审计日志四大核心机制，帮你快速加固生产实例。

为什么需要这份安全加固清单

自托管意味着"安全由你自己负责"。Obsidian Arc 默认提供了分层防御，但每一项都需要管理员按场景启用，而不是照单全开：

• 登录侧：TOTP 两步验证保护账号身份；
• 注册与高危操作侧：Turnstile 与 PoW 拦截自动化脚本；
• 运营侧：审计日志回答"哪位管理员在什么时候改了什么"。

这四层机制分别解决不同问题，配合 docs/features/security.md 中的注册条件、频率限制等设置，构成完整防线。

TOTP 两步验证：密码之外的第二道锁

TOTP（基于时间的一次性密码，RFC 6238）让用户在输入密码后，还需输入手机身份验证器生成的六位验证码。别人即使拿到了密码，没有你的手机也登录不了。

实现位于 internal/totp/totp.go：6 位数字、30 秒有效期、允许前后 1 个时间步的时钟偏差，且同一验证码不可重复使用，比较过程采用恒定时间避免时序泄露。

四步绑定身份验证器

在 设置 → 安全 中点击"设置两步验证"，按向导完成：

1. 安装应用：任选支持 TOTP 的应用，如 Google Authenticator、Authy、1Password、Bitwarden 等；
2. 扫码绑定：扫描页面二维码，或手动输入密钥（类型选"基于时间"）；
3. 输入验证码：验证通过后才真正开启，中途关闭页面对账户无影响；
4. 保存恢复码：10 个恢复码只显示这一次，请保存在手机以外的地方。

完整步骤见 docs/features/two-factor.md。

恢复码与管理员强制策略

• 手机丢失：登录时点击"改用恢复码"，每个恢复码只能用一次；手机和恢复码都丢失时，联系管理员重置。
• 强制策略：管理后台 安全 → 两步验证 支持四档：不强制 / 管理员进后台必须绑定 / 所有管理员必须绑定 / 所有用户必须绑定。为防止管理员把自己锁在后台外，操作者本人必须先开启两步验证，否则保存会被拒绝。
• 进入后台二次验证：可要求管理员进入管理后台时再验证一次，支持"每次进入 / 无操作超时 / 定期验证"三种模式，还能在 IP 或浏览器变化时自动作废解锁状态。

⚠️ 强制策略覆盖网页登录、第三方登录和 SSH 终端，但不影响已创建的 API 密钥，密钥安全请另行管理。

Turnstile 人机验证：拦下自动化注册与刷量请求

Turnstile 是 Cloudflare 提供的人机验证组件，在 Obsidian Arc 中只用在"自动化成功代价最高"的几个入口：

源码在 internal/turnstile/turnstile.go，几个值得注意的设计细节：

• 密钥永不离开服务器进程：secret 在设置界面为只写、响应中一律打码；
• 验证端点硬编码，管理员无法把它指向"来者不拒"的第三方；
• 区分失败类型：用户没通过挑战返回 403（challenge_failed），Cloudflare 服务故障返回 503（challenge_unavailable），便于监控区分"一波机器人"和"验证服务宕机"；
• 验证请求携带客户端 IP（remoteip），把令牌绑定到调用者，防止"一次解出、千次转卖"。

📌 上线前检查清单：站点域名与密钥配对是否正确、服务器能否访问验证服务。详见 docs/features/security.md。

PoW 工作量证明：本地化的防批量注册拼图

没有外部依赖时，Obsidian Arc 用 ALTCHA 风格的**有界工作量证明（Proof-of-Work）**替代外部验证码：

1. 服务器基于随机 salt 与有界数字生成挑战，用HMAC-SHA256签名；
2. 客户端从 0 递增 nonce，找到哈希匹配的答案并提交；
3. 服务器校验签名、有效期，并拒绝已被使用过的 salt（防重放）。

实现在 internal/pow/pow.go 与 internal/pow/salts.go：

• 重放防护：已用 salt 默认存在内存中；调用UseSaltStore后可存入数据库，让共享同一数据库的多实例互不重复放行；
• 过期与限流：挑战过期（ErrExpired）、nonce 超界（ErrMaxExceeded）、请求过频（ErrRateLimited）都会明确报错；
• 难度可分档：低于当前难度档位的旧挑战会被拒绝（ErrBelowTier），管理员可以在运行中抬高门槛。

对普通用户几乎无感，但对注册脚本是一笔实实在在的 CPU 成本——这正是它的价值所在。

审计日志与安全事件：让管理操作可追溯

Obsidian Arc 把"日志"拆成三本账，各司其职：

审计日志记录了什么

由 internal/audit/audit.go 实现，后台每一条路由默认挂载审计包装器——"新接口天然就是被审计的接口"：

• 每一次后台写操作：新增、修改、删除、执行，无论成功、失败还是权限不足被拒绝；被拒绝的尝试也会记在发起人名下；
• 敏感读操作：查看他人对话列表或内容；
• 终端管理命令：网页终端或 SSH 中执行的管理命令同样留痕，来源标记为console:web/console:ssh；
• 字段级变更：修改设置或编辑账号时，记录每个字段的旧值与新值。

每条记录包含时间、操作人及角色、操作对象（含当时的名称快照）、状态码、耗时、来源、IP 与客户端。

敏感信息自动打码

请求内容写入前先脱敏：字段名含password、secret、token、key的值一律替换为***；密钥类设置只记录"已更改"，不记录新旧值；上传内容只记长度或类型。

保留策略与终端查询

• 默认保留180 天，由后台例行清理任务删除过期记录；保留时长（audit.retention_days）仅超级管理员可改，范围 30–3650 天；
• 查看需要单独的"审计日志"权限（audit）；
• 后台不提供删除单条记录的能力，防篡改请把数据库备份纳入保留计划。

终端中可直接查询：

audit list --outcome failed audit list --actor alice --limit 20 audit show <id>

安全事件（注册审核结果、限权、聊天验证）则走独立的安全日志，不混入普通请求日志，列表接口见 internal/admin/security_events.go。完整说明见 docs/admin/logs-and-auditing.md。

安全加固快速核对表

按上表逐项核对后，你的 Obsidian Arc 实例将具备身份、入口、行为、追溯四个层面的完整防护。