From 90643348b16f604b0ae01909f19a12643426d3a8 Mon Sep 17 00:00:00 2001
From: root <root@minecraft-server>
Date: Mon, 4 May 2026 19:54:03 +0800
Subject: [PATCH] =?UTF-8?q?fix:=20=E8=A1=A5=E5=85=85=E4=BF=AE=E5=A4=8D=20h?=
 =?UTF-8?q?eredoc=20=E5=8D=95=E5=BC=95=E5=8F=B7=E5=92=8C=20venv=20?=
 =?UTF-8?q?=E5=BC=BA=E5=88=B6=E8=A6=81=E6=B1=82?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Bug4: heredoc 单引号 'ONEBOTEOF' → ONEBOTEOF
  让 ${QQREBOT_HOST} 被 bash 自动展开，无需手动替换
  同时更新了 README 中的说明文字

- Bug10: 添加 venv 创建步骤到打包环节
  严禁 --break-system-packages
  自动检测并 apt install python3-venv 兜底
---
 README.md | 17 +++++++++++++++--
 1 file changed, 15 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index d9de030..825fba5 100644
--- a/README.md
+++ b/README.md
@@ -152,7 +152,7 @@ mkdir -p /opt/napcat/qq_data
 > ⚠️ onebot11.json 默认不存在，需手动创建。NapCat v4 使用 `network` 配置格式（非旧版 `http{} ws{}` 格式）。
 
 ```bash
-cat > /opt/napcat/config/onebot11.json << 'ONEBOTEOF'
+cat > /opt/napcat/config/onebot11.json << ONEBOTEOF
 {
   "network": {
     "httpServers": [
@@ -189,7 +189,7 @@ ONEBOTEOF
 
 > `httpServers`：OneBot HTTP API，脚本通过此端口发送消息/管理群组。
 > `httpClients`：NapCat 将消息事件通过 HTTP POST 推送到 qqrebot。
-> `httpClients[0].url` 中 `${QQREBOT_HOST}` 需替换为实际地址（同机部署时为 `172.17.0.1:25580`）。Docker 的默认 bridge 网关是 `172.17.0.1`，可通过 `docker network inspect bridge` 确认。
+> `httpClients[0].url` 使用 `${QQREBOT_HOST}`，因 heredoc 无引号，bash 会自动展开为 `172.17.0.1:25580`（Docker bridge 网关 IP）。可通过 `docker network inspect bridge` 确认。
 
 #### 2.4 启动 NapCat Docker 容器
 
@@ -324,8 +324,21 @@ systemctl enable --now qqrebot
 
 **打包（必须在目标主机上执行，因含 C 扩展）：**
 
+> ⚠️ **必须使用虚拟环境，严禁 `--break-system-packages`。**
+> 如果 `python3 -m venv` 报错（如 Debian 未安装 `python3-venv`），先用包管理器安装：`apt-get install -y python3-venv`。
+
 ```bash
 cd /path/to/chatrebot_aireply_plug
+
+# 确保可以创建虚拟环境（Debian 默认未安装 python3-venv）
+if ! python3 -m venv --help &>/dev/null; then
+  apt-get update && apt-get install -y python3-venv
+fi
+
+# 创建并激活虚拟环境（严禁 --break-system-packages）
+python3 -m venv .venv
+source .venv/bin/activate
+
 pip install -r requirements.txt
 python3 package.py
 ```