feat(监控): 完善系统监控、登录状态与访问审计能力

docs/guides/system-monitoring-operations.md

@@ -0,0 +1,82 @@
+# 系统监测简易运维指南
+
+## 定位与访问边界
+
+系统监测用于单实例或小规模 CTMS 部署的日常巡检、访问追踪和初步故障定位，不替代集中式指标、日志和告警平台。监测页面及 `/api/v1/permission-monitoring/*` 仅允许系统管理员访问，项目 PM 不具备系统级监测权限。
+
+## 健康检查
+
+- `GET /health`：进程存活探针，不访问数据库，适合判断 HTTP 服务是否仍在响应。
+- `GET /readyz`：服务就绪探针，会执行数据库查询；数据库不可用时返回 `503`。Nginx、安装脚本和后端容器健康检查均使用或暴露此探针。
+- `GET /api/v1/permission-monitoring/health`：管理员健康详情，包含权限检查质量、缓存、进程内告警、数据库延迟、权限/安全日志写入队列、留存任务和监测表数据量。
+
+部署后的最小检查：
+
+```bash
+curl -fsS http://127.0.0.1:8888/health
+curl -fsS http://127.0.0.1:8888/readyz
+docker compose ps
+```
+
+## 数据留存
+
+后台任务在应用启动后立即清理一次，之后按固定间隔执行。默认策略：
+
+- 权限访问日志和安全访问日志：90 天。
+- 权限小时指标：400 天。
+- 账号登录活动：180 天。
+- 清理周期：86400 秒（每天）。
+
+可通过后端环境变量调整：
+
+```text
+MONITORING_ACCESS_LOG_RETENTION_DAYS=90
+MONITORING_METRIC_RETENTION_DAYS=400
+MONITORING_RETENTION_INTERVAL_SECONDS=86400
+USER_LOGIN_ACTIVITY_RETENTION_DAYS=180
+USER_SESSION_ONLINE_SECONDS=300
+```
+
+访问日志留存范围为 7–3650 天，指标留存范围为 30–3650 天，清理周期范围为 60–604800 秒。修改后需重启后端。正式环境部署新版本前必须先执行 Alembic migration。
+
+账号管理页的“在线”状态由服务端会话心跳计算：最近 `USER_SESSION_ONLINE_SECONDS` 秒内成功心跳且未退出的会话视为在线。登录记录仅保存客户端类型、版本、登录/最近活动/退出时间；不保存 Token、密码或原始 IP。
+
+## 来源地图服务器位置
+
+来源地图中的服务器标记不使用固定城市或前端坐标。后端启动时按以下顺序确定部署服务器的公网地址，并缓存定位结果：
+
+1. `MONITORING_SERVER_PUBLIC_IP` 明确指定的公网 IP，适用于禁止主动访问公网探测服务的生产网络。
+2. `FRONTEND_PUBLIC_URL` 主机名解析出的公网 IP。
+3. `MONITORING_PUBLIC_IP_DISCOVERY_URLS` 配置的公网出口 IP 查询服务。
+
+默认公网查询服务为 `https://api64.ipify.org,https://icanhazip.com`，单次超时 2.5 秒。解析成功后通过本地 ip2region 数据库确定属地，再由后端转换为地图坐标；解析失败时 API 返回 `server_location: null`，地图不会使用任意默认城市代替。
+
+受限网络建议显式配置：
+
+```text
+MONITORING_SERVER_PUBLIC_IP=<部署服务器公网IP>
+MONITORING_PUBLIC_IP_DISCOVERY_URLS=
+```
+
+公网 IP 仅用于服务端定位，不写入来源分析 API 响应或浏览器界面。
+
+## 日志完整性与隐私
+
+- 每个请求由服务端生成 UUID 请求标识，并通过响应头 `X-Request-ID` 返回；权限日志和安全日志以该标识消除同一请求的重复统计。
+- 写入队列保持非阻塞；队列满或数据库批次写入最终失败时不阻塞业务请求，但会累计丢弃量、失败批次、队列占用和最近错误时间，并在管理员健康页显示降级。
+- 请求正文不采集。请求头仅保留运维白名单字段，认证、Cookie、密钥类字段统一脱敏；查询参数中的令牌、账号、受试者/患者、姓名、邮箱、电话、证件和地址类值会替换为 `[redacted]`。
+- IP、User-Agent 和请求路径仍属于运维审计数据，应按管理员最小授权和上述留存策略管理，不应复制到公开工单或通知正文。
+
+## 常见异常处理
+
+| 现象 | 首要检查 | 建议处理 |
+| --- | --- | --- |
+| `/health` 正常、`/readyz` 返回 503 | 数据库容器、连接串、迁移状态 | 检查 `docker compose ps`、数据库日志和 `alembic current` |
+| 日志写入器降级 | 队列占用、丢弃量、失败批次、最近错误 | 检查数据库连接和容量；恢复后确认队列回落并重启以清零进程累计计数 |
+| 留存任务异常 | 最近成功/错误时间 | 检查数据库权限、表结构和后端日志，确认 migration 已升级 |
+| 页面显示“可能是上次成功结果” | 对应 API 或网络请求 | 使用刷新按钮重试，并结合 `/readyz` 与浏览器网络面板定位 |
+| 安全事件突然增多 | 分类、来源 IP、路径和状态码 | 优先核对敏感路径探测、5xx 和无效令牌，不要仅按 4xx 总量或地理位置判断 |
+
+## 当前边界与后续升级
+
+权限缓存指标、告警列表和写入器累计计数仍为单进程内存状态，重启后会重置；当前也不负责短信、邮件、Slack 等外部通知。需要多实例部署、跨重启趋势、值班通知或长期容量分析时，应接入 Prometheus/OpenTelemetry、集中日志和 Alertmanager 类告警链路，并保留本模块作为管理员快速诊断入口。