feat: geolocate anonymous widget visitors

docs/runbooks/anonymous-visitor-geoip.md

@@ -0,0 +1,48 @@
+# Anonymous Web Widget GeoIP 配置
+
+GoChat 可使用本地 MaxMind-compatible City MMDB，将无姓名的 Web Widget 联系人命名为省市客户，例如 `河北保定客户`。
+
+## 配置
+
+生产 Compose 使用两个变量：
+
+```dotenv
+GOCHAT_GEOIP_DB_PATH=/run/gochat/geoip/GeoLite2-City.mmdb
+GOCHAT_GEOIP_DB_FILE=../../.secrets/GeoLite2-City.mmdb
+```
+
+`GOCHAT_GEOIP_DB_FILE` 是宿主机上的 MMDB 文件，`GOCHAT_GEOIP_DB_PATH` 是容器内的只读挂载路径。生产 Compose 会把文件挂载到 GoChat 和 worker 容器；不要把数据库文件提交到 Git 或打包进镜像。
+
+开发和 Quickstart 默认不启用 GeoIP。需要验证时，设置 `GOCHAT_GEOIP_DB_PATH` 并把数据库挂载到对应容器内路径。
+
+## 数据库来源和更新
+
+使用具备合法授权的 MaxMind-compatible City 数据库。下载、授权、更新频率和访问权限由部署方负责；数据库文件应由运行用户可读、不可写。
+
+更新步骤：
+
+1. 在宿主机下载并校验新的 MMDB 文件；
+2. 原子替换 `GOCHAT_GEOIP_DB_FILE` 指向的文件；
+3. 重启 `gochat` 和 `worker`，让进程重新打开数据库；
+4. 查看启动日志中的 `GeoIP database opened`；
+5. 用隔离 Widget 验证一个省市、一个直辖市和一个无记录地址。
+
+## 故障回退
+
+数据库缺失、损坏、过期或无法读取不会阻断服务启动或 Widget 请求。服务会记录一次启动告警，匿名联系人使用 `匿名客户`。
+
+临时关闭功能：
+
+```dotenv
+GOCHAT_GEOIP_DB_PATH=
+```
+
+然后重新部署或重启服务即可，无需数据库迁移或数据回滚。
+
+## 隐私边界
+
+- IP 只在服务端请求处理期间用于本地查询；
+- 一期不把原始 IP 写入联系人、日志或公开 Widget 响应；
+- 只保存系统生成名称所需的省、市元数据；
+- IP 归属地是网络出口的近似位置，不能代表客户精确所在地；
+- 反向代理场景必须正确配置 `server.trusted_proxies`，否则不要信任 `X-Forwarded-For`。