first

domain-api/deploy/linux/README.md

@@ -111,6 +111,27 @@ sudo cp /opt/domaincheck/domain-api/deploy/systemd/domain-worker.service /etc/sy
 - `Group`
 - `Environment`
 
+### 权限注意
+
+正式 `systemd` 服务用户必须对下面这些路径有写权限：
+
+- `domain-api/runtime/`
+- `domainCheck/detect_worker.log`
+
+如果之前曾用 `root` 手工跑过 API 或 Worker，可能会留下 `root` 所有者的运行目录或日志文件，导致正式服务态出现下面这类问题：
+
+- `/api/v1/imports/upload` 因无法创建 `runtime/imports/` 返回 `500`
+- Worker 因无法写 `detect_worker.log` 进入循环重启
+
+必要时先修正所有者：
+
+```bash
+sudo chown -R www:www /opt/domaincheck/domain-api/runtime
+sudo touch /opt/domaincheck/domainCheck/detect_worker.log
+sudo chown www:www /opt/domaincheck/domainCheck/detect_worker.log
+sudo chmod 664 /opt/domaincheck/domainCheck/detect_worker.log
+```
+
 ## 六、启动顺序
 
 ```bash
@@ -135,6 +156,18 @@ journalctl -u domaincheck-api -n 200 --no-pager
 journalctl -u domaincheck-worker -n 200 --no-pager
 ```
 
+如果计划让 Web 后台里的“运行中心”控制 Worker 启停或触发 API 重启，还需要给服务用户补一条免密 sudo 规则。测试服当前使用的是：
+
+```text
+Defaults:www !requiretty
+Cmnd_Alias DOMAINCHECK_WORKER_CTL = /usr/bin/systemctl start domaincheck-worker, /usr/bin/systemctl stop domaincheck-worker
+Cmnd_Alias DOMAINCHECK_WORKER_SHOW = /usr/bin/systemctl show domaincheck-worker --no-page --property=ActiveState\,SubState\,MainPID
+Cmnd_Alias DOMAINCHECK_API_RESTART = /usr/bin/systemctl restart domaincheck-api, /usr/bin/systemctl --no-block restart domaincheck-api
+www ALL=(root) NOPASSWD: DOMAINCHECK_WORKER_CTL, DOMAINCHECK_WORKER_SHOW, DOMAINCHECK_API_RESTART
+```
+
+其中 API 自重启建议使用 `systemctl --no-block restart domaincheck-api`，这样接口可以先返回成功，再由 `systemd` 异步完成服务切换，避免调用方因为等待自身停机而拿到 `500`。
+
 ## 七、联调检查
 
 ### 1. API 健康检查