debug

2026-04-16 22:07:45 +08:00
parent ebf632e651
commit e64c23a021
8 changed files with 147 additions and 38 deletions
--- a/docs/17_domainCheck_全流程部署实操手册.md
+++ b/docs/17_domainCheck_全流程部署实操手册.md
@@ -71,6 +71,26 @@
 - Redis `6+`
 - Nginx

+关键说明：
+
+- 这里的 Python 不是“系统自带什么就用什么”
+- 必须明确安装 `python3.11`
+- 不能只装系统默认 `python3`
+- 因为后续部署命令直接使用的是 `python3.11 -m venv .venv`
+
+推荐先执行：
+
+```bash
+dnf install -y python3.11 python3.11-devel
+python3.11 --version
+```
+
+期望输出类似：
+
+```text
+Python 3.11.x
+```
+
 ### 2. 目录约定

 统一使用：
@@ -109,6 +129,12 @@ ln -s /www/wwwroot/getDomain/domainCheck /opt/domaincheck/domainCheck

 当前建议统一走 `git` 管理和更新，不再手工散传目录。

+执行口径：
+
+- 这里建议直接使用 `root`
+- 不建议使用 `www` 用户执行整套部署命令
+- 因为后面还会接着写 `systemd`、`/etc/default/`、`/opt/domaincheck/` 和服务启停
+
 第一次部署建议：

 ```bash
@@ -138,6 +164,17 @@ git checkout main
 git pull --ff-only origin main
 ```

+### 1.1 先确认 Python 3.11 已安装
+
+如果当前机器还没有 `python3.11`，先执行：
+
+```bash
+dnf install -y python3.11 python3.11-devel
+python3.11 --version
+```
+
+只有确认 `python3.11` 命令存在后，再继续下面的虚拟环境步骤。
+
 ### 2. 创建 Python 虚拟环境

 ```bash
--- a/docs/18_domainCheck_CentOS9一键复制部署与更新文档.md
+++ b/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
--- a/domain-api/deploy/multi-region/install_mainland_controller_quick.conf.example
+++ b/domain-api/deploy/multi-region/install_mainland_controller_quick.conf.example
@@ -1,4 +1,3 @@
-GIT_REPO_URL="YOUR_GIT_REPO_URL"
 GIT_BRANCH="main"
 DB_NAME="domain"
 DB_USER="domainuser"
--- a/domain-api/deploy/multi-region/install_mainland_controller_quick.sh
+++ b/domain-api/deploy/multi-region/install_mainland_controller_quick.sh
@@ -14,7 +14,6 @@ fi
 # shellcheck disable=SC1090
 source "${CONFIG_FILE}"

-: "${GIT_REPO_URL:=YOUR_GIT_REPO_URL}"
 : "${GIT_BRANCH:=main}"
 : "${DB_NAME:=domain}"
 : "${DB_USER:=domainuser}"
@@ -29,15 +28,16 @@ BASE_DIR="/opt/domaincheck"
 DOMAINCHECK_DIR="${BASE_DIR}/domainCheck"
 DOMAIN_API_DIR="${BASE_DIR}/domain-api"

-if [[ "${GIT_REPO_URL}" == "YOUR_GIT_REPO_URL" || "${DB_PASSWORD}" == "CHANGE_ME_DB_PASSWORD" || "${SYNC_SHARED_TOKEN}" == "CHANGE_ME_SYNC_SHARED_TOKEN" ]]; then
-  echo "请先修改配置文件中的必填项：GIT_REPO_URL / DB_PASSWORD / SYNC_SHARED_TOKEN"
+if [[ "${DB_PASSWORD}" == "CHANGE_ME_DB_PASSWORD" || "${SYNC_SHARED_TOKEN}" == "CHANGE_ME_SYNC_SHARED_TOKEN" ]]; then
+  echo "请先修改配置文件中的必填项：DB_PASSWORD / SYNC_SHARED_TOKEN"
  exit 1
 fi

 mkdir -p "${WORKSPACE_ROOT}"
-cd "${WORKSPACE_ROOT}"
 if [[ ! -d "${REPO_DIR}/.git" ]]; then
-  git clone "${GIT_REPO_URL}" getDomain
+  echo "未找到仓库目录：${REPO_DIR}"
+  echo "全新机器首次部署，必须先手动执行 git clone，把仓库拉到 /www/wwwroot/getDomain"
+  exit 1
 fi
 cd "${REPO_DIR}"
 git fetch --all
--- a/domain-api/deploy/multi-region/install_mainland_worker_quick.conf.example
+++ b/domain-api/deploy/multi-region/install_mainland_worker_quick.conf.example
@@ -1,4 +1,3 @@
-GIT_REPO_URL="YOUR_GIT_REPO_URL"
 GIT_BRANCH="main"
 DB_NAME="domain"
 DB_USER="domainuser"
--- a/domain-api/deploy/multi-region/install_mainland_worker_quick.sh
+++ b/domain-api/deploy/multi-region/install_mainland_worker_quick.sh
@@ -14,7 +14,6 @@ fi
 # shellcheck disable=SC1090
 source "${CONFIG_FILE}"

-: "${GIT_REPO_URL:=YOUR_GIT_REPO_URL}"
 : "${GIT_BRANCH:=main}"
 : "${DB_NAME:=domain}"
 : "${DB_USER:=domainuser}"
@@ -30,15 +29,16 @@ BASE_DIR="/opt/domaincheck"
 DOMAINCHECK_DIR="${BASE_DIR}/domainCheck"
 DOMAIN_API_DIR="${BASE_DIR}/domain-api"

-if [[ "${GIT_REPO_URL}" == "YOUR_GIT_REPO_URL" || "${DB_PASSWORD}" == "CHANGE_ME_DB_PASSWORD" || "${SYNC_SHARED_TOKEN}" == "CHANGE_ME_SYNC_SHARED_TOKEN" || "${MAINLAND_CONTROLLER_IP}" == "127.0.0.1" ]]; then
-  echo "请先修改配置文件中的必填项：GIT_REPO_URL / DB_PASSWORD / SYNC_SHARED_TOKEN / MAINLAND_CONTROLLER_IP"
+if [[ "${DB_PASSWORD}" == "CHANGE_ME_DB_PASSWORD" || "${SYNC_SHARED_TOKEN}" == "CHANGE_ME_SYNC_SHARED_TOKEN" || "${MAINLAND_CONTROLLER_IP}" == "127.0.0.1" ]]; then
+  echo "请先修改配置文件中的必填项：DB_PASSWORD / SYNC_SHARED_TOKEN / MAINLAND_CONTROLLER_IP"
  exit 1
 fi

 mkdir -p "${WORKSPACE_ROOT}"
-cd "${WORKSPACE_ROOT}"
 if [[ ! -d "${REPO_DIR}/.git" ]]; then
-  git clone "${GIT_REPO_URL}" getDomain
+  echo "未找到仓库目录：${REPO_DIR}"
+  echo "全新机器首次部署，必须先手动执行 git clone，把仓库拉到 /www/wwwroot/getDomain"
+  exit 1
 fi
 cd "${REPO_DIR}"
 git fetch --all
--- a/domain-api/deploy/multi-region/install_overseas_quick.conf.example
+++ b/domain-api/deploy/multi-region/install_overseas_quick.conf.example
@@ -1,4 +1,3 @@
-GIT_REPO_URL="YOUR_GIT_REPO_URL"
 GIT_BRANCH="main"
 API_DOMAIN="api.domain.com"
 ADMIN_DOMAIN="admin.domain"
--- a/domain-api/deploy/multi-region/install_overseas_quick.sh
+++ b/domain-api/deploy/multi-region/install_overseas_quick.sh
@@ -14,7 +14,6 @@ fi
 # shellcheck disable=SC1090
 source "${CONFIG_FILE}"

-: "${GIT_REPO_URL:=YOUR_GIT_REPO_URL}"
 : "${GIT_BRANCH:=main}"
 : "${API_DOMAIN:=api.domain.com}"
 : "${ADMIN_DOMAIN:=admin.domain}"
@@ -31,15 +30,16 @@ DOMAINCHECK_DIR="${BASE_DIR}/domainCheck"
 DOMAIN_API_DIR="${BASE_DIR}/domain-api"
 DOMAIN_WEB_DIR="${BASE_DIR}/domain-web"

-if [[ "${GIT_REPO_URL}" == "YOUR_GIT_REPO_URL" || "${DB_PASSWORD}" == "CHANGE_ME_DB_PASSWORD" ]]; then
-  echo "请先修改配置文件中的必填项：GIT_REPO_URL / DB_PASSWORD"
+if [[ "${DB_PASSWORD}" == "CHANGE_ME_DB_PASSWORD" ]]; then
+  echo "请先修改配置文件中的必填项：DB_PASSWORD"
  exit 1
 fi

 mkdir -p "${WORKSPACE_ROOT}"
-cd "${WORKSPACE_ROOT}"
 if [[ ! -d "${REPO_DIR}/.git" ]]; then
-  git clone "${GIT_REPO_URL}" getDomain
+  echo "未找到仓库目录：${REPO_DIR}"
+  echo "全新机器首次部署，必须先手动执行 git clone，把仓库拉到 /www/wwwroot/getDomain"
+  exit 1
 fi
 cd "${REPO_DIR}"
 git fetch --all