feat: 管理端网站监控，浏览量写入独立 monitor.db
请求日志按日 JSONL；page_views 不进主库，避免统计数据撑大 jiang13.db。 Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
105
docs/docker-data.md
Normal file
105
docs/docker-data.md
Normal file
@@ -0,0 +1,105 @@
|
||||
# Docker 数据持久化说明
|
||||
|
||||
Docker 部署时**默认只挂载一个目录**，不是分别映射「数据库文件夹」和「附件文件夹」两个卷。
|
||||
|
||||
## 挂载对应关系
|
||||
|
||||
| 宿主机 | 容器内 |
|
||||
|--------|--------|
|
||||
| 任意目录或 named volume（如 `jiang13-data`） | **`/data`** |
|
||||
|
||||
**示例：**
|
||||
|
||||
```bash
|
||||
docker run -d --name jiang13 \
|
||||
-p 3000:3000 \
|
||||
-v /你的路径/jiang13-data:/data \
|
||||
--restart unless-stopped \
|
||||
hangzhang714128/jiang13-forum:latest
|
||||
```
|
||||
|
||||
或在 `docker-compose.yml` 中：
|
||||
|
||||
```yaml
|
||||
volumes:
|
||||
- jiang13-data:/data
|
||||
# 或绑定宿主机目录：
|
||||
# - ./data:/data
|
||||
```
|
||||
|
||||
## `/data` 目录结构
|
||||
|
||||
数据库与附件都在同一个 `/data` 挂载内：
|
||||
|
||||
```
|
||||
/data/
|
||||
├── jiang13.db # SQLite 主数据库（不含浏览量）
|
||||
├── monitor.db # 网站监控 page_views
|
||||
├── uploads/ # 附件根目录
|
||||
│ ├── avatars/ # 用户头像
|
||||
│ └── posts/ # 帖子图片等
|
||||
├── logs/
|
||||
│ └── access/ # 网站监控请求日志（按日 jsonl）
|
||||
│ └── YYYY-MM-DD.jsonl
|
||||
├── IP2LOCATION-LITE-DB3.BIN # 可选：IPv4 城市库（监控）
|
||||
├── IP2LOCATION-LITE-DB3.IPV6.BIN # 可选：IPv6 城市库
|
||||
├── GeoLite2-ASN.mmdb # 可选：ASN/运营商
|
||||
├── GeoLite2-Country.mmdb # 可选：国家兜底
|
||||
├── .jwt_secret # JWT 密钥（自动生成）
|
||||
├── filter_words.txt # 敏感词配置
|
||||
└── jiang13.log # 运行日志（若启用）
|
||||
```
|
||||
|
||||
| 用途 | 路径 |
|
||||
|------|------|
|
||||
| 主数据库 | `/data/jiang13.db` |
|
||||
| 监控浏览量 | `/data/monitor.db` |
|
||||
| 附件 | `/data/uploads/` |
|
||||
| 请求日志（监控） | `/data/logs/access/` |
|
||||
| 地理库（可选） | `/data/IP2LOCATION-LITE-DB3*.BIN`、`GeoLite2-ASN.mmdb` 等 |
|
||||
|
||||
官方镜像不要求拆成两个 volume；挂好 `/data` 即可同时持久化 SQLite、上传文件与监控日志。
|
||||
|
||||
地理库与 BIN **不内置**于 Docker 镜像。详见 [网站监控设计](monitor.md)。管理端展示完整客户端 IP（不做脱敏）。
|
||||
|
||||
## 设计说明：为何只挂一个 `/data`
|
||||
|
||||
对本项目（单容器、SQLite、默认可本地存附件）而言，**一个数据卷是合理默认**：
|
||||
|
||||
- 部署成本最低，不易漏挂导致「重启丢图 / 丢库」
|
||||
- 备份、迁移时拷贝或快照整个 `/data` 即可恢复站点状态
|
||||
- 密钥（`.jwt_secret`）、敏感词与库同目录，避免「库还在、登录全失效」这类半残状态
|
||||
|
||||
若你习惯「数据库文件夹 / 附件文件夹」分开填写：在本镜像中它们分别是 **`/data` 下的文件与子目录**，不是两个独立容器路径。
|
||||
|
||||
附件特别大、希望对象存储时：优先使用管理后台的 **S3 兼容存储**，而不是拆 Docker 卷。
|
||||
|
||||
## 后续计划（可选增强，非必须）
|
||||
|
||||
按优先级，仅在有明确需求时做：
|
||||
|
||||
1. **文档与面板提示（优先）**
|
||||
- README / 1Panel 说明中固定话术：「只需挂载 `/data`；数据库=`jiang13.db`，监控=`monitor.db`，附件=`uploads/`」。
|
||||
- 本页保持为权威说明，避免用户误以为漏了一个卷。
|
||||
|
||||
2. **进阶：同一 DataDir 下拆挂子路径（文档级，无需改代码）**
|
||||
若必须把库与附件分到不同宿主机磁盘，可在仍使用容器 `/data` 的前提下分别绑定，例如：
|
||||
|
||||
```yaml
|
||||
volumes:
|
||||
# 推荐：父目录一次挂载
|
||||
- /ssd/jiang13:/data
|
||||
# 或仅把附件分到大容量盘（需保证 /data 下其余文件仍可写）
|
||||
- /ssd/jiang13:/data
|
||||
- /hdd/jiang13-uploads:/data/uploads
|
||||
```
|
||||
|
||||
拆挂时仍要保证 `/data` 下 `.jwt_secret` 等文件可写；不熟悉 Docker 时请继续只用单个 `/data` 挂载。
|
||||
|
||||
3. **产品级：可配置上传根目录（中期）**
|
||||
- 环境变量或 `app.ini` 支持 `upload_dir` 与 `data_dir` 分离。
|
||||
- Docker 示例改为可选双卷；**默认仍单卷**，避免破坏现有部署。
|
||||
|
||||
4. **不做的事**
|
||||
- 不为「看起来像 WordPress」而强制双卷。
|
||||
- 不在未支持分离配置前，在 UI 里假装有两个独立数据根。
|
||||
76
docs/monitor.md
Normal file
76
docs/monitor.md
Normal file
@@ -0,0 +1,76 @@
|
||||
# 网站监控设计说明
|
||||
|
||||
管理端「网站监控」：轻量自建访问统计，对标 1Panel 思路——**请求流水写文件、访客地理写独立库**，开启后不拖慢前台读帖。
|
||||
|
||||
## 双通道数据
|
||||
|
||||
| 数据 | 存储 | 用途 |
|
||||
|------|------|------|
|
||||
| 请求日志 | `{DataDir}/logs/access/YYYY-MM-DD.jsonl` | 请求日志页、请求数/流量/4xx·5xx、实时曲线 |
|
||||
| page_views | `{DataDir}/monitor.db`（SQLite） | 浏览量/访客、国家/省/城市/运营商排行与地图 |
|
||||
|
||||
请求日志**只写 jsonl**，不进 SQLite。删除过期 `.jsonl` 即释放磁盘。
|
||||
|
||||
`page_views` **不进主库** `jiang13.db`。后台「导出备份」只含主库，不含浏览量。
|
||||
|
||||
### 文件行格式（JSONL）
|
||||
|
||||
每行一条 JSON，字段包括：`t`（RFC3339）、`method`、`path`、`status`、`bytes`、`duration_ms`、`ip`、`ua`、`referer`、`country`、`region`、`region_iso`、`city`、`asn`、`as_org`、`is_bot`。
|
||||
|
||||
### 保留天数
|
||||
|
||||
- `monitor_retention_days`：仅 **page_views**（默认 30）
|
||||
- `monitor_access_log_retention_days`：请求日志文件（默认 7）
|
||||
|
||||
## 地理数据文件
|
||||
|
||||
放在数据目录（与 `jiang13.db` 同级），有则加载、无则静默降级：
|
||||
|
||||
| 文件 | 用途 |
|
||||
|------|------|
|
||||
| `IP2LOCATION-LITE-DB3.BIN` | IPv4 国家/省/城市 |
|
||||
| `IP2LOCATION-LITE-DB3.IPV6.BIN` | IPv6 国家/省/城市 |
|
||||
| `GeoLite2-ASN.mmdb` | ASN / 运营商 |
|
||||
| `GeoLite2-Country.mmdb` | 可选：BIN 未命中时国家兜底 |
|
||||
|
||||
CDN 头（如 `CF-IPCountry`）仅在本地库无国家码时补全。不落 Lat/Lon/Zip/TimeZone。管理端展示**完整客户端 IP**。
|
||||
|
||||
写入时做本地中文映射（省/常见城市/运营商）；`country` 存 ISO2，展示用中文名。
|
||||
|
||||
## 写入路径（性能）
|
||||
|
||||
1. 中间件：监控关闭或命中排除规则则直接放行；否则 `c.Next()` 后**仅入队**轻量字段（不查 BIN/ASN、不写盘）。
|
||||
2. 后台 flush：出队 → Geo + 中文映射 → append 当日 jsonl + 更新内存实时环。
|
||||
3. 队列上限 8192，满则丢弃新日志（保护内存与磁盘）。
|
||||
4. pageview 信标 QPS 低，可在写入时同步 Geo 后写独立 `monitor.db`（不占用主库连接）。
|
||||
|
||||
**热路径零 Geo、零写库、零写文件。**
|
||||
|
||||
## 请求日志口径（排除规则）
|
||||
|
||||
默认只关心**前台访客**，排除管理员刷后台产生的壳请求：
|
||||
|
||||
- `/admin`、`/api/admin/`
|
||||
- `/api/me`、`/api/site-branding`
|
||||
- `/health`、`/uploads/`、`/media/`、静态后缀、`/api/monitor/pageview` 等
|
||||
|
||||
设置页可「恢复推荐排除规则」。不强制覆盖用户已保存的自定义列表。
|
||||
|
||||
浏览量/访客仍来自前台路由 pageview（后台路径本身不上报）。
|
||||
|
||||
## 实时与聚合
|
||||
|
||||
- 近 1 分钟 / 近 1 小时：内存环（flush 时更新），避免扫全文件。
|
||||
- 今日请求数等：内存日累加器（进程内；重启后自新流量累积，论坛量级可接受）。
|
||||
- 地理排行：仅 `page_views`。
|
||||
|
||||
## 诊断
|
||||
|
||||
```bash
|
||||
go run ./cmd/monitor-geo-check -db data/monitor.db -ip 14.109.35.246
|
||||
```
|
||||
|
||||
## 明确不做
|
||||
|
||||
- 不用 CIDR；不把请求日志写入 SQLite；不把 page_views 写入主库
|
||||
- 不做街道级地图；Docker 镜像不内置 BIN/MMDB
|
||||
Reference in New Issue
Block a user