From 35f3979b52cf6f40dc8e4a38b7eea7a94d37de25 Mon Sep 17 00:00:00 2001
From: Claw <claw@local>
Date: Mon, 4 May 2026 17:41:42 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=A2=9E=E5=8A=A0=E8=B8=A9=E5=9D=91?=
 =?UTF-8?q?=E6=8C=87=E5=8D=97=EF=BC=88systemd/=E7=AB=AF=E5=8F=A3=E7=A1=AC?=
 =?UTF-8?q?=E7=BC=96=E7=A0=81/ConfigManager/venv/gunicorn=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/README.md b/README.md
index 73e64c6..1f908e9 100755
--- a/README.md
+++ b/README.md
@@ -202,6 +202,54 @@ GATEWAY_TOKEN  = "YOUR_GATEWAY_TOKEN"    # Gateway 鉴权 Token
 cd /path/to/qq-agent/workspace/scripts
 python3 qq_get_groups.py
 ```
+
+## 常见问题 / 踩坑指南
+
+### 1. systemd 下只有 stdin/stdout，没有持久化日志
+
+本仓库设计为通过 systemd 托管，`run.sh` 中的 gunicorn 输出全部走 stdout/stderr。systemd 会自动捕获到 journald。
+
+查看日志：
+
+```bash
+journalctl -u qqrebot --since "5 minutes ago" -f
+```
+
+如果发现日志回滚太短，在 service 中设置 `StandardOutput=journal+console`。
+
+### 2. `app.py` 端口硬编码
+
+`app.py` 的 `__main__` 直接将端口写死在 `port=25580`，不走 `config.toml`。这意味着：
+
+- `python3 app.py` 直接运行 → **无视配置**，始终占 25580
+- `run.sh`（gunicorn）→ **自动读取配置**，正常
+
+如果直接 `python3 app.py` 启动报 `Address already in use`，检查是否跟 gunicorn 实例抢端口。
+
+### 3. ConfigManager 内部字典不自动刷新
+
+当插件首次部署，`config/插件名/config.toml` 尚不存在时，`ConfigManager.__init__` 会通过 `build_config_dict()` 扫描目录。此时文件不存在，内部 `self.config` 为空。
+
+`BasePlugin.config` 属性的异常处理会触发 `_ensure_config_exists()` 创建文件，但 **ConfigManager 的 `self.config` 不会被刷新**，第二次 `load_config("config")` 仍然 KeyError。解决方法：`_ensure_config_exists` 创建文件后调用 `self._config_manager.build_config_dict()` 手动刷新。
+
+### 4. python3-venv 缺失
+
+纯净 Debian/Ubuntu 没有 `python3-venv`：
+
+```bash
+apt install python3.13-venv   # 替换 .13 为实际版本
+```
+
+否则 `run.sh` 创建虚拟环境会直接失败。
+
+### 5. gunicorn / waitress 不在 requirements.txt 中
+
+```bash
+# requirements.txt 未包含，由启动脚本单独安装
+# run.sh:  pip install gunicorn
+# run.bat: pip install waitress
+```
+
 ## 设计优势
 
 1. **解耦设计**：插件与核心系统完全解耦