debug

docs/17_domainCheck_全流程部署实操手册.md

@@ -1,8 +1,21 @@
-# 17 domainCheck 全流程部署实操手册
+# 17 domainCheck 手工部署实操手册
 
 ## 一、文档目标
 
-这份文档不是设计说明，也不是零散检查单，而是给实际部署时直接照着做的“全流程操作手册”。
+这份文档只讲一件事：
+
+> 不依赖一键脚本，完全手工完成部署、更新、排障和扩容。
+
+它不是设计说明，也不是零散检查单，而是给实际部署时直接照着做的“手工操作手册”。
+
+文档边界：
+
+- 这里只讲手工部署
+- 不使用 `install_overseas_quick.sh`
+- 不使用 `install_mainland_controller_quick.sh`
+- 不使用 `install_mainland_worker_quick.sh`
+- 如果你想走傻瓜式复制部署，请改看：
+  - [18_domainCheck_CentOS9一键复制部署与更新文档.md](/www/wwwroot/getDomain/docs/18_domainCheck_CentOS9一键复制部署与更新文档.md:1)
 
 适用场景：
 
@@ -181,7 +194,38 @@ python3.11 --version
 cd /opt/domaincheck/domainCheck
 python3.11 -m venv .venv
 source .venv/bin/activate
-pip install -r requirements.txt
+pip install --upgrade pip
+python3.11 - <<'PY'
+from pathlib import Path
+
+source = Path("requirements.txt")
+target = Path("requirements.linux.txt")
+raw = source.read_bytes()
+for encoding in ("utf-8", "utf-16", "utf-16-le", "utf-16-be", "gbk"):
+    try:
+        text = raw.decode(encoding)
+        break
+    except UnicodeDecodeError:
+        continue
+else:
+    raise SystemExit("无法解析 requirements.txt 编码")
+
+skip_prefixes = (
+    "pywin32==",
+    "pywin32-ctypes==",
+    "twisted-iocpsupport==",
+    "win32-setctime==",
+)
+lines = []
+for line in text.splitlines():
+    normalized = line.strip().lstrip("\ufeff")
+    if normalized.lower().startswith(skip_prefixes):
+        continue
+    lines.append(normalized)
+
+target.write_text("\n".join(lines) + "\n", encoding="utf-8")
+PY
+pip install -r requirements.linux.txt
 ```
 
 然后补 API 依赖：
@@ -191,6 +235,12 @@ cd /opt/domaincheck/domain-api
 /opt/domaincheck/domainCheck/.venv/bin/pip install fastapi uvicorn pydantic-settings psycopg2-binary redis openpyxl python-multipart
 ```
 
+补充说明：
+
+- 这里不能直接在 Linux 上裸跑 `pip install -r requirements.txt`
+- 因为桌面版历史依赖里包含 `pywin32` 等 Windows-only 包
+- 手工部署时也必须先生成 `requirements.linux.txt` 再安装
+
 ### 3. 配置数据库和 Redis
 
 确保 PostgreSQL 和 Redis 可用。

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

@@ -1,4 +1,4 @@
-# 18 domainCheck CentOS9 一键复制部署与更新文档
+# 18 domainCheck CentOS9 全自动一键部署与更新文档
 
 ## 一、文档用途
 
@@ -6,6 +6,14 @@
 
 > 给你一套可以直接复制执行的命令，完成 `1 台国外机器 + 2 台国内机器` 的傻瓜式部署和后续更新。
 
+文档边界：
+
+- 这里只讲一键自动部署
+- 默认你会使用仓库里的 3 个一键脚本
+- 不展开手工逐条部署步骤
+- 如果你想完全手工部署，请改看：
+  - [17_domainCheck_全流程部署实操手册.md](/www/wwwroot/getDomain/docs/17_domainCheck_全流程部署实操手册.md:1)
+
 统一前提：
 
 - 系统：`CentOS Stream 9`
@@ -49,6 +57,7 @@ MAINLAND_WORKER_NODE_CODE=mainland-worker-01
 MAINLAND_CONTROLLER_IP=国内controller机器IP
 
 NODE_VERSION=20
+NODE_NVM_DIR=
 ```
 
 最少必须先替换这 5 个：
@@ -59,6 +68,16 @@ NODE_VERSION=20
 - `ADMIN_DOMAIN`
 - `MAINLAND_CONTROLLER_IP`
 
+如果你用 `root` 执行一键脚本，但 `nvm` 实际装在别的用户目录下，再额外补一个：
+
+- `NODE_NVM_DIR`
+
+例如：
+
+```text
+NODE_NVM_DIR=/home/www/.nvm
+```
+
 ## 三、统一约定
 
 ### 1. 仓库目录
@@ -210,7 +229,18 @@ nvm use 20
 
 - 国外机器如果要构建前端，必须先确保 `nvm` 可用
 - 一键部署脚本会调用 `nvm install 20` 和 `nvm use 20`
-- 所以脚本执行用户的 `HOME` 下必须已经安装好 `nvm`
+- 如果你用 `root` 执行脚本，而 `nvm` 实际装在别的用户目录下：
+  - 不需要改成 `www` 执行脚本
+  - 直接在 `install_overseas_quick.conf` 里填写：
+    - `NODE_NVM_DIR=/home/www/.nvm`
+- 当前一键脚本会按这个顺序找 Node 运行环境：
+  - `NODE_NVM_DIR`
+  - 当前环境变量里的 `NVM_DIR`
+  - `/root/.nvm`
+  - `/home/www/.nvm`
+  - `/www/server/nvm`
+  - `/usr/local/nvm`
+  - 最后再尝试系统全局 `node` 和 `npm`
 
 ### 7. 你实际应该怎么选
 

domain-api/deploy/multi-region/install_overseas_quick.conf.example

@@ -5,3 +5,4 @@ DB_USER="domainuser"
 DB_PASSWORD="CHANGE_ME_DB_PASSWORD"
 OVERSEAS_NODE_CODE="overseas-control-01"
 NODE_VERSION="20"
+NODE_NVM_DIR=""

domain-api/deploy/multi-region/install_overseas_quick.sh

@@ -26,6 +26,7 @@ source "${CONFIG_FILE}"
 : "${DB_PASSWORD:=CHANGE_ME_DB_PASSWORD}"
 : "${OVERSEAS_NODE_CODE:=overseas-control-01}"
 : "${NODE_VERSION:=20}"
+: "${NODE_NVM_DIR:=}"
 
 WORKSPACE_ROOT="/www/wwwroot"
 REPO_DIR="${WORKSPACE_ROOT}/getDomain"
@@ -111,15 +112,50 @@ cat >"${DOMAIN_WEB_DIR}/.env.production" <<EOF
 VITE_API_BASE_URL=https://${API_DOMAIN}/api/v1
 EOF
 
-export NVM_DIR="${HOME}/.nvm"
+cd "${DOMAIN_WEB_DIR}"
-if [[ ! -s "${NVM_DIR}/nvm.sh" ]]; then
+NODE_READY=false
-  echo "未找到 nvm，请先为当前执行用户安装 nvm"
+
+resolve_nvm_dir() {
+  local candidate
+  for candidate in \
+    "${NODE_NVM_DIR}" \
+    "${NVM_DIR:-}" \
+    "/root/.nvm" \
+    "/home/www/.nvm" \
+    "/www/server/nvm" \
+    "/usr/local/nvm"
+  do
+    if [[ -n "${candidate}" && -s "${candidate}/nvm.sh" ]]; then
+      echo "${candidate}"
+      return 0
+    fi
+  done
+  return 1
+}
+
+if RESOLVED_NVM_DIR="$(resolve_nvm_dir)"; then
+  export NVM_DIR="${RESOLVED_NVM_DIR}"
+  # shellcheck disable=SC1090
+  source "${NVM_DIR}/nvm.sh"
+  echo "检测到 nvm：${NVM_DIR}"
+  nvm install "${NODE_VERSION}"
+  nvm use "${NODE_VERSION}"
+  NODE_READY=true
+elif command -v node >/dev/null 2>&1 && command -v npm >/dev/null 2>&1; then
+  echo "未检测到 nvm，改用系统已安装的 node/npm"
+  echo "当前 node 版本：$(node -v)"
+  NODE_READY=true
+fi
+
+if [[ "${NODE_READY}" != "true" ]]; then
+  echo "未找到可用的 Node 运行环境。"
+  echo "请执行以下任一方案后重试："
+  echo "1. 用 root 安装 nvm，并确保 /root/.nvm/nvm.sh 存在"
+  echo "2. 在 install_overseas_quick.conf 中填写 NODE_NVM_DIR，例如：/home/www/.nvm"
+  echo "3. 预先安装系统全局 node 和 npm"
   exit 1
 fi
-source "${NVM_DIR}/nvm.sh"
+
-nvm install "${NODE_VERSION}"
-nvm use "${NODE_VERSION}"
-cd "${DOMAIN_WEB_DIR}"
 npm install
 npm run build