From e406d73334c9f1549fb441fb73eb3e0b78a5a632 Mon Sep 17 00:00:00 2001
From: Your Name <you@example.com>
Date: Thu, 16 Apr 2026 13:28:34 +0800
Subject: [PATCH] debug

---
 docs/05_domainCheck_Linux部署清单.md | 32 +++++++++++++++++++++++----
 domain-api/deploy/linux/README.md    | 33 +++++++++++++++++++++++-----
 2 files changed, 56 insertions(+), 9 deletions(-)

diff --git a/docs/05_domainCheck_Linux部署清单.md b/docs/05_domainCheck_Linux部署清单.md
index 0389acc..b59ef54 100644
--- a/docs/05_domainCheck_Linux部署清单.md
+++ b/docs/05_domainCheck_Linux部署清单.md
@@ -72,10 +72,34 @@
 3. 上传 `domain-web`
 4. 创建 Python 虚拟环境并安装依赖
 5. 初始化或连接 PostgreSQL/Redis
-6. 安装 `systemd` 服务
-7. 启动 `domaincheck-api`
-8. 启动 `domaincheck-worker`
-9. 验证 Web 后台与运行中心
+6. 先执行 `domainCheck/init_database.py` 初始化数据库结构
+7. 安装 `systemd` 服务
+8. 启动 `domaincheck-api`
+9. 启动 `domaincheck-worker`
+10. 验证 Web 后台与运行中心
+
+### 数据库初始化
+
+如果目标 PostgreSQL 是一套新库，必须先执行：
+
+```bash
+cd /opt/domaincheck/domainCheck
+python3 init_database.py
+```
+
+执行完成后，建议至少确认这些表已存在：
+
+- `domains`
+- `detect_tasks`
+- `domain_detections`
+- `domain_blacklist`
+- `sensitive_words`
+
+如果未先初始化数据库，下面这些接口会因为 `UndefinedTable` 直接失败：
+
+- `/api/v1/dashboard/overview`
+- `/api/v1/detect/status`
+- `/api/v1/imports/summary`
 
 ### 前端补充
 
diff --git a/domain-api/deploy/linux/README.md b/domain-api/deploy/linux/README.md
index 1bdb6c6..069bd91 100644
--- a/domain-api/deploy/linux/README.md
+++ b/domain-api/deploy/linux/README.md
@@ -66,7 +66,30 @@ REDIS_DB=0
 - `ADMIN_USERNAME`
 - `ADMIN_PASSWORD`
 
-## 四、部署 systemd
+## 四、先初始化数据库结构
+
+如果 PostgreSQL 使用的是一套新库，必须先执行旧项目里自带的初始化脚本：
+
+```bash
+cd /opt/domaincheck/domainCheck
+python3 init_database.py
+```
+
+这个脚本会创建并补齐当前 API/Worker 依赖的核心业务表和字段，至少包括：
+
+- `domains`
+- `detect_tasks`
+- `domain_blacklist`
+- `sensitive_words`
+- `domain_detections`
+
+如果这一步没做，API 虽然能启动，但下面这些接口会直接因为表不存在而 `500`：
+
+- `/api/v1/dashboard/overview`
+- `/api/v1/detect/status`
+- `/api/v1/imports/summary`
+
+## 五、部署 systemd
 
 模板文件：
 
@@ -88,7 +111,7 @@ sudo cp /opt/domaincheck/domain-api/deploy/systemd/domain-worker.service /etc/sy
 - `Group`
 - `Environment`
 
-## 五、启动顺序
+## 六、启动顺序
 
 ```bash
 sudo systemctl daemon-reload
@@ -112,7 +135,7 @@ journalctl -u domaincheck-api -n 200 --no-pager
 journalctl -u domaincheck-worker -n 200 --no-pager
 ```
 
-## 六、联调检查
+## 七、联调检查
 
 ### 1. API 健康检查
 
@@ -155,14 +178,14 @@ python deploy/linux/smoke_test.py --base-url http://127.0.0.1:8100
 python deploy/linux/smoke_test.py --base-url http://127.0.0.1:8100 --web-url http://127.0.0.1
 ```
 
-## 七、上线建议
+## 八、上线建议
 
 - 先保持 `Windows 桌面版 + Web/Linux` 并行一段时间
 - 先让 Web 后台接管设置、导入、筛选、导出、日志
 - 再让 Linux Worker 接管主检测任务
 - 确认稳定后，再逐步淡出桌面检测端
 
-## 八、联调诊断采集
+## 九、联调诊断采集
 
 如需导出一份联调诊断包，可执行：