# ADR-003: nginx 敏感路径 access_log 关闭

**状态**: ✅ 已采纳
**日期**: 2026-06-14
**决策者**: 宋献 + Claude 评审
**关联**: [[风险跟踪表]] 第十节 / 评审报告 `workbuddy-2026-06-14-P0安全.md`

---

## 1. 背景

nginx `access_log` 默认记录所有请求,含敏感信息:
- `Authorization: Bearer <token>`
- `?token=<JWT>`
- `Cookie: session=<sid>`

敏感路径必须关闭 access_log,避免 token 永久落盘。

## 2. 决策

**敏感路径一律 `access_log off`**,具体见下表。

## 3. 关闭清单

| 路径 | 原因 | access_log |
|---|---|---|
| `/ws/` | WebSocket token 鉴权 | `off` |
| `/api/v1/auth/login` | 密码登录 | `off` |
| `/api/v1/auth/refresh` | token 刷新 | `off` |
| `/api/v1/h5/oauth/callback` | OAuth2 回调 | `off` |
| `/api/v1/wecom/callback` | 企微回调(验证 URL 含 echostr) | `off` |
| `/api/v1/agents/login` | 坐席登录 | `off` |
| `/api/v1/upload*` | 文件上传(可能含敏感文件名) | `off` |
| `/health` `/healthz` `/readyz` | 健康检查(高频) | `off` |

## 4. 实现

```nginx
server {
    # 全局
    access_log /var/log/nginx/access.log;
    error_log  /var/log/nginx/error.log;

    # WS(敏感)
    location /ws/ {
        access_log off;
        proxy_pass http://backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    # 登录(敏感)
    location ~ ^/api/v1/(auth|agents)/login$ {
        access_log off;
        proxy_pass http://backend;
    }

    # 健康检查(高频)
    location ~ ^/(health|healthz|readyz)$ {
        access_log off;
        proxy_pass http://backend;
    }

    # 其它
    location / {
        proxy_pass http://backend;
    }
}
```

## 5. error_log 仍开启

⚠️ **error_log 仍开** —— 4xx/5xx 错误需要留痕(token 在 error log 里出现频率低,且 error log 有 TTL 自动切割)。

## 6. 日志清理脚本

`/etc/logrotate.d/nginx` 配:
```
/var/log/nginx/*.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
    create 0640 www-data adm
    sharedscripts
    prerotate
        if [ -d /etc/logrotate.d/httpd-prerotate ]; then \
            run-parts /etc/logrotate.d/httpd-prerotate; \
        fi
    endscript
    postrotate
        invoke-rc.d nginx rotate >/dev/null 2>&1
    endscript
}
```

## 7. 风险与缓解

| 风险 | 缓解 |
|---|---|
| 漏关某个敏感路径 | 定期审计(任务 W-5,workbuddy 跑) |
| 调试时无 access_log 难定位 | debug 时临时开 `access_log /tmp/debug.log;` |
| 攻击者利用关闭日志 | error_log 仍开,异常请求有记录 |