站点安全与访问审计模块 · Vibecoding 任务提示词
# 站点安全与访问审计模块 · Vibecoding 任务提示词
## 角色与目标
你是负责现有站点安全改造的资深全栈工程师。在不破坏既有业务功能的前提下,为站点补齐:
1. 管理员与普通用户的多方式登录;
2. 后台用户管理;
3. 敏感信息库(密码本)的动态码解锁;
4. 全站访问日志与业务审计;
5. IP 情报、黑名单、单 IP 阈值与风险提示页。
技术栈由你阅读项目后确定,不要假设语言、框架、数据库或部署方式。若项目已有同类能力,先复用、再扩展,避免重复造轮子。
## 0. 先读代码,再动手
- 先梳理:登录/会话/权限、用户模型、后台路由与接口守卫、限流与防刷、日志、配置管理、反向代理与部署方式。
- 先输出 5–8 行实施计划与主要风险点,再开始修改。
- 不重构无关模块;不做未被要求的"顺手优化"。
## 1. 强制研究阶段(联网 + GitHub)
必须先使用**联网搜索**与 **GitHub 代码/仓库检索**,再选型:
1. 反向代理 / CDN 场景下如何解析真实客户端 IP(`Forwarded`、`X-Forwarded-For` 信任链、防伪造、IPv6、可信代理层数)。
2. IP 地理位置 + 代理 / VPN / Tor / 机房 / 爬虫识别方案(托管 API、离线数据库、自建),比较精度、覆盖、免费额度、延迟、隐私与维护成本。
3. 访问日志与审计日志的工程实践(异步写入、批量、保留期、索引、脱敏、防篡改)。
4. 按 IP 限流 / 封禁 / 风险页拦截的成熟实现与常见坑。
要求:
- 每个主题至少对比 3 个方案,记录来源链接、许可或免费额度、优缺点。
- 不得凭记忆猜第三方接口字段,必须查官方文档;任何 API Key 只放服务端。
- 选型必须提供降级方案:外部情报服务不可用时,日志记录与拦截仍要工作。
- 不建议把付费服务作为唯一方案;确需 Key 时,必须有无 Key 的可用降级路径。
- 检索关键词示例(中英皆可):
- "real client ip behind reverse proxy Forwarded X-Forwarded-For trusted proxy github"
- "IP geolocation proxy VPN Tor detection API comparison free tier"
- "self-hosted geoip database proxy detection github"
- "audit log design best practices request logging retention"
- "per-ip rate limit blocklist redirect risk page github"
- 在交付报告中附关键链接,并说明"为什么选它、限制是什么"。
## 2. 功能需求
### 2.1 登录与身份
- 管理员:使用动态验证码(TOTP)登录;若项目已有可用登录方式,可作为过渡保留。
- 普通用户:登录页提供两种方式,由用户自选:
a) 手机号 + 动态验证码(TOTP);
b) 手机号 + 短信验证码(无需密码)。
- 动态码与短信码必须:一次性消费、有有效期、失败次数限制、拒绝重放、按来源节流;短信码要按用途隔离(登录码不能用于安全操作)。
- 普通用户登录后只能进入前台或用户中心;**任何后台页面与后台接口都必须在服务端拒绝**,不能只靠前端隐藏。
### 2.2 后台用户管理
- 列表展示:显示名、手机号、角色、动态码是否已配置、最近登录、创建时间。
- 新增用户:输入手机号 → 服务端生成 2FA 密钥(只展示一次,附可手动录入的密钥 / 二维码链接)→ 可选显示名 → 创建。
- 角色强制为普通用户;接口层禁止创建管理员、禁止通过参数提权。
- 新用户可登录前台,但不能进入后台。
- 修改手机号 / 修改 2FA 密钥:操作前必须向**当前绑定手机号**发送短信验证码并校验通过;验证码一次性、限时、限次。
- 强制改手机号 / 删除用户:当手机号已停用或为占位号时,允许管理员在**已登录并通过管理员身份校验**后直接执行;删除需二次确认。
- 禁止删除自己、禁止删除最后一个管理员;所有强制操作写审计日志。
- 手机号唯一、格式校验;密钥轮换后旧密钥立即失效。
### 2.3 敏感信息库(密码本)
- 取消"主密码输入"作为解锁方式,改为**验证动态码(TOTP)解锁**。
- 内容在服务端加密存储;解密密钥不得由用户密码派生、不得下发浏览器;密钥来自服务端密钥管理。
- 解锁后签发**短期解锁会话**(建议 30 分钟,可配置),支持手动"锁定"立即失效;会话过期或失效后接口返回明确的"已锁定"状态,前端回到锁定界面。
- 历史数据:若旧版本用主密码在客户端加密,改版后无法解密,必须:
- 识别旧格式并显式标记"旧数据不可解密";
- 提供重新录入入口,或提供一次性迁移(用户仍记得旧密码时);
- **绝不静默删除或伪装成空内容**。
- 列表、搜索、新增、编辑、删除均需解锁会话;解锁与增删改都要写审计。
### 2.4 访问日志(全站)
- 记录每次页面与 API 请求:时间、真实客户端 IP、IP 来源头、代理链、方法、路径、查询串(脱敏)、状态码、耗时、UA、Referer。
- 静态资源、健康检查、内部服务调用不记录(或可配置忽略)。
- 写入必须**异步 / 批量**,不阻塞请求;队列有上限,数据库故障时降级丢日志而不是拖垮站点。
- 保留期可配置(建议 30 天),到期自动清理;按时间、IP、路径建立索引,保证后台查询可分页。
- 后台可按 IP、路径、风险类型、状态等筛选;列表分页。
### 2.5 IP 情报与真实 IP
- 正确解析代理头:支持 `Forwarded`、`X-Forwarded-For`、`CF-Connecting-IP`、`True-Client-IP`、`X-Real-IP`;只在请求经过可信代理(本机 / 内网反代)时信任,并按"从右往左取第一个公网地址"的规则确定客户端 IP;最左侧可伪造值只能作为链路证据,不能作为判定依据。
- 识别内网 / 保留地址(IPv4 / IPv6),避免把 127.0.0.1 当成访客。
- 情报字段:国家 / 地区 / 城市、ISP / 组织、ASN、代理、VPN、Tor、机房 / 云主机、爬虫;缺失时明确显示"未知",不要猜。
- 给出"真实 IP 判定":高 / 中 / 低置信度 + 依据(命中代理标记、机房网段、代理链跳数等)。
- 外部查询必须缓存(内存 + 持久化),设置 TTL、并发合并、每分钟预算;服务不可用时回退到只记录基础信息;提供可选更高精度数据源的配置项。
### 2.6 审计日志(业务 + 安全)
- 记录所有后台写操作:操作人、角色、动作、目标类型 / ID、方法、路径、状态码、IP、UA、时间。
- 额外记录安全事件:各登录方式成功、密码本解锁、用户新增 / 改号 / 强改 / 轮换 2FA / 删除、黑名单与阈值变更、风险页配置变更。
- 审计只允许管理员查询,普通用户不可读写;写入失败不得影响业务请求。
- 保留期可配置(建议 180 天);后台支持按分类 / 操作人 / 关键字筛选与分页。
### 2.7 黑名单、阈值与风险页
- IP 黑名单:新增 / 移除,支持原因与有效期(永久或到期自动失效);变更写审计。
- 单 IP 阈值:为指定 IP 配置"时间窗口 + 最大次数";超过后该 IP 进入拦截态。
- 拦截表现:
- 页面请求统一跳转到**自定义风险页**;
- API 请求返回明确的拒绝响应(如 403),响应中包含可读原因;
- 风险页必须无需登录即可访问,且不被拦截逻辑再次拦截,避免重定向循环。
- 风险页为新建独立页面,标题与正文可后台配置;默认正文必须为:`请求存在风险异常,禁止访问`;页面不索引(noindex)。
- 防止管理员自锁:后台路径或已认证管理员请求应豁免拦截(或提供可靠的应急放行机制),并在文档 / 界面中说明。
- 阈值计数使用固定或滑动窗口并定期清理;服务重启导致计数重置可接受,但需在说明中注明。
### 2.8 后台界面
- 新增 / 编辑 / 配置一律用**弹窗**,不整页铺表单;多步骤用弹窗内步骤切换(步骤条 + 仅渲染当前步 + 上一步 / 下一步)。
- 表单弹窗宽度克制,内容区内部滚动,头尾操作固定;含表格的批量 / 详情弹窗可更宽。
- 访问日志页:筛选、分页、IP 详情弹窗(含情报、真实 IP 判定、代理链逐跳、最近请求、请求统计)。
- IP 详情内提供:一键拉黑 / 取消拉黑、一键复制"AI 排查 Prompt"、一键设置 / 修改该 IP 阈值。
- 一键复制内容格式:`帮我看看 <IP> 是否可疑 IP(是否真实访问者、是否代理 / VPN / Tor / 机房),以下是它的情报与所有 / 最近请求日志:<内容>`,包含情报、风险标记、判定依据、代理链、请求记录。
- 访问控制页:风险页文案与开关、黑名单表格、阈值表格,均支持新增 / 删除 / 编辑。
## 3. 安全与工程约束
- 所有后台接口逐个做服务端鉴权与角色校验,不能只靠隐藏菜单。
- 动态码 / 短信码:一次性消费、有效期、失败限次、拒绝重放、按 IP / 账号节流;密钥与验证码不得写入日志。
- 日志脱敏:查询串中的 token / password / code / secret / key 等一律打码;不记录请求体中的敏感字段。
- 加密:敏感库内容使用服务端密钥加密;密钥 / 凭据只放环境变量或密钥管理系统,不写仓库、不下发前端。
- 异步任务(日志 / 情报查询)不得阻塞主请求;外部服务调用必须设置超时与降级。
- 数据保留:日志与审计设置明确保留期与清理机制,避免无限增长。
- 防伪造:任何来自客户端的 IP 头都不能单独作为封禁依据;封禁 / 限流使用可信解析结果。
- 防误伤:黑名单 / 阈值必须可快速撤销,后台始终可访问;提供可靠的解除入口。
- 兼容性:支持 IPv4 / IPv6;反向代理、CDN、容器网络下均能正确取 IP。
## 4. 验收清单(实现后逐条自测并在报告中给出证据)
1. 管理员动态码登录成功;错误码 / 过期码 / 重放码被拒绝;连续失败触发限流。
2. 普通用户动态码登录(手机号 + 码)与短信验证码登录均成功;普通用户访问后台页面与后台接口均被拒绝。
3. 修改手机号 / 2FA 必须短信验证;验证码错误 / 过期 / 复用失败;验证码只对当前手机号有效。
4. 强制改手机号与删除用户可用;不能删自己 / 最后管理员;相关操作有审计记录。
5. 密码本只能动态码解锁;解锁会话到期后接口变为"已锁定";手动锁定立即失效;旧格式数据被标记且可重新录入。
6. 页面与 API 请求均产生访问日志;代理后能记录真实 IP;伪造 `X-Forwarded-For` 不会改变判定 IP(只出现在代理链);国家 / 地区 / 代理标记正确展示或显示未知。
7. 黑名单:页面请求跳风险页、API 返回拒绝;风险页可访问且文案可配置;移除后恢复;管理员不被锁死。
8. 单 IP 阈值:超过阈值后页面跳风险页 / API 拒绝;计数窗口与清理正常;修改规则后行为按缓存周期生效。
9. 业务审计:每种后台写操作都有记录(谁、何时、对什么、结果、IP);登录 / 解锁 / 用户 / 访问控制事件有记录;普通用户无法读取审计。
10. 性能与稳定性:日志异步写入不拖慢请求;队列有界;数据库 / 外部情报服务故障时站点可用。
11. 数据保留与隐私:保留期生效;无敏感信息落日志;密钥不出服务端。
12. UI:分页 / 筛选 / 详情可用;弹窗步骤切换正常;后台导航选中态在二级路由下正确(例如 `/admin/audit` 与 `/admin/audit/business` 不能同时高亮)。
13. 现有功能回归通过;无无关改动。
## 5. 交付报告
- 研究结论:每个主题对比了哪些方案、选择与原因、链接。
- 架构与数据模型:新增实体、保留期、索引、请求生命周期中的处理顺序。
- 风险与限制:情报精度、免费额度、IP 伪造边界、旧数据迁移、管理员豁免策略。
- 验证证据:命令 / 接口 / 截图 / 日志片段,逐条对应验收清单。
- 变更清单与部署说明(环境变量、所需权限)。
## 6. 禁止事项
- 禁止只做前端隐藏而不做服务端鉴权。
- 禁止把最左侧 `X-Forwarded-For` 当作真实客户端 IP。
- 禁止把动态码 / 短信码 / 密码 / 密钥写入日志或审计详情。
- 禁止同步写日志阻塞请求、禁止无上限内存队列。
- 禁止在未说明风险的情况下删除旧加密数据。
- 禁止通过新增用户接口创建管理员或允许角色提权。
- 禁止为了"顺便优化"重构无关模块。