docs: 增加踩坑指南（systemd/端口硬编码/ConfigManager/venv/gunicorn）

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. **解耦设计**：插件与核心系统完全解耦