debug

docs/18_domainCheck_CentOS9一键复制部署与更新文档.md

@@ -32,7 +32,6 @@
 正式执行本文命令前，先把下面这些变量替换成你自己的真实值。
 
 ```text
-GIT_REPO_URL=你的仓库地址
 GIT_BRANCH=main
 
 API_DOMAIN=api.domain.com
@@ -55,7 +54,6 @@ NODE_VERSION=20
 
 最少必须先替换这 6 个：
 
-- `GIT_REPO_URL`
 - `DB_PASSWORD`
 - `SYNC_SHARED_TOKEN`
 - `API_DOMAIN`
@@ -87,6 +85,70 @@ git checkout main
 git pull --ff-only origin main
 ```
 
+### 3.1 首次全新机器先做什么
+
+如果这台机器是第一次部署，而且本机还没有：
+
+```text
+/www/wwwroot/getDomain
+```
+
+那么要先手动拉一次代码，因为脚本文件本身也在仓库里。
+
+首次最小步骤：
+
+```bash
+mkdir -p /www/wwwroot
+cd /www/wwwroot
+git clone 你的仓库地址 getDomain
+cd getDomain
+git checkout main
+git pull --ff-only origin main
+```
+
+然后再：
+
+1. 复制对应的 `.conf.example`
+2. 编辑 `.conf`
+3. 执行对应的 `.sh`
+
+如果这台机器已经有仓库目录了，后面再执行脚本时，脚本内部会自动做 `git fetch / checkout / pull`，不需要你每次手动拉代码。
+
+关键结论：
+
+- 新机器第一次：必须先手动 `git clone`
+- 后续执行脚本：不再负责 `clone`
+- 脚本只负责“基于已存在仓库做部署或更新”
+
+### 3.2 这些命令用哪个用户执行
+
+结论：
+
+- 整套部署命令建议统一使用 `root`
+- 不建议用 `www` 执行部署脚本
+
+原因：
+
+- 脚本会写：
+  - `/etc/default/...`
+  - `/etc/systemd/system/...`
+  - `/opt/domaincheck/...`
+- 脚本会执行：
+  - `systemctl enable`
+  - `systemctl restart`
+  - `chown`
+  - 可能还有 `dnf`
+
+这些都属于 `root` 口径，不适合 `www` 用户执行。
+
+最稳的执行方式：
+
+```bash
+sudo -i
+```
+
+然后再继续后面的复制、编辑和执行脚本。
+
 ### 4. 统一软链接
 
 所有机器都统一建立：
@@ -147,6 +209,31 @@ ln -sfn /www/wwwroot/getDomain/domainCheck /opt/domaincheck/domainCheck
   - 直接按本文的纯命令部署
   - 这样最轻、最稳、最容易横向复制
 
+### 8. Python 3.11 必须单独安装
+
+- 这里不能只依赖系统默认 `python3`
+- 必须明确安装 `python3.11`
+- 因为本文后续所有部署命令都直接使用：
+  - `python3.11 -m venv .venv`
+
+安装命令：
+
+```bash
+dnf install -y python3.11 python3.11-devel
+```
+
+安装后先验证：
+
+```bash
+python3.11 --version
+```
+
+期望输出类似：
+
+```text
+Python 3.11.x
+```
+
 ## 四、最短复制块
 
 这一节给你三段最短命令。
@@ -158,10 +245,9 @@ ln -sfn /www/wwwroot/getDomain/domainCheck /opt/domaincheck/domainCheck
 
 ### 1. 国外主控机最短复制块
 
-先把下面 8 个值替换掉再执行：
+先把下面 7 个值替换掉再执行：
 
 ```text
-GIT_REPO_URL
 GIT_BRANCH
 API_DOMAIN
 ADMIN_DOMAIN
@@ -182,10 +268,7 @@ bash /www/wwwroot/getDomain/domain-api/deploy/multi-region/install_overseas_quic
 ```
 
 ```bash
-mkdir -p /www/wwwroot
-cd /www/wwwroot
-git clone GIT_REPO_URL getDomain || true
-cd getDomain
+cd /www/wwwroot/getDomain
 git fetch --all
 git checkout GIT_BRANCH
 git pull --ff-only origin GIT_BRANCH
@@ -262,10 +345,9 @@ curl http://127.0.0.1:8100/api/v1/runtime/readiness
 
 ### 2. 国内 controller 最短复制块
 
-先把下面 5 个值替换掉再执行：
+先把下面 4 个值替换掉再执行：
 
 ```text
-GIT_REPO_URL
 GIT_BRANCH
 DB_PASSWORD
 SYNC_SHARED_TOKEN
@@ -283,10 +365,7 @@ bash /www/wwwroot/getDomain/domain-api/deploy/multi-region/install_mainland_cont
 ```
 
 ```bash
-mkdir -p /www/wwwroot
-cd /www/wwwroot
-git clone GIT_REPO_URL getDomain || true
-cd getDomain
+cd /www/wwwroot/getDomain
 git fetch --all
 git checkout GIT_BRANCH
 git pull --ff-only origin GIT_BRANCH
@@ -358,10 +437,9 @@ bash deploy/multi-region/check_mainland_controller.sh
 
 ### 3. 国内 worker 最短复制块
 
-先把下面 6 个值替换掉再执行：
+先把下面 5 个值替换掉再执行：
 
 ```text
-GIT_REPO_URL
 GIT_BRANCH
 DB_PASSWORD
 SYNC_SHARED_TOKEN
@@ -380,10 +458,7 @@ bash /www/wwwroot/getDomain/domain-api/deploy/multi-region/install_mainland_work
 ```
 
 ```bash
-mkdir -p /www/wwwroot
-cd /www/wwwroot
-git clone GIT_REPO_URL getDomain || true
-cd getDomain
+cd /www/wwwroot/getDomain
 git fetch --all
 git checkout GIT_BRANCH
 git pull --ff-only origin GIT_BRANCH