xhs_crawler/README_CN.md

XHS Cloud 稳定版（Docker，自建服务器）

适用：自建服务器固定 IP、一个采集账号；每周拉取 500~600 个发布账号的笔记/数据；需要 Web 界面 + 实时日志 + 一键触发登录（noVNC）。

端口约定（可改）

• Web：28000（容器 8000）
• noVNC：26080（容器 6080）

你们只开放 10000-50000 端口的话，把这两个端口改到范围内即可。

一、首次部署（非 1Panel）

cd /opt
sudo mkdir -p xhs_cloud && sudo chown -R $USER:$USER xhs_cloud
# 上传并解压本 zip 到 /opt/xhs_cloud
cd /opt/xhs_cloud

1）构建镜像（首次）

如遇到 Docker Hub 网络超时，先保证 build 已完成；运行 compose 时加 --pull never 避免再拉取。

sudo docker build --provenance=false --no-cache -t xhs-cloud-web:stable -f Dockerfile .
sudo docker build --provenance=false --no-cache -t xhs-cloud-novnc:stable -f Dockerfile.novnc .

2）启动

sudo docker compose up -d --pull never
sudo docker ps

3）访问

• Web 控制台：http://<服务器IP>:28000
• noVNC：http://<服务器IP>:26080/vnc_auto.html

二、登录（Web 一键触发）

1. 打开 Web 控制台 → 点击【启动登录】
2. Web 会提示打开 noVNC（或自动打开）
3. 进入 noVNC 桌面后，会自动弹出 Chromium → 扫码登录小红书
4. 登录成功后会写入：data/storage_state.json，浏览器会自动关闭

登录流程状态文件：data/.login_status.json

三、采集（正常情况无需 noVNC）

• 直接在 Web 控制台点【开始采集】即可
• 日志通过 WebSocket 推送到页面

四、验证命令（排错时用）

1）确认端口映射

sudo docker port xhs-web
sudo docker port xhs-novnc
sudo ss -lntp | egrep "(:28000|:26080)\b"

2）确认 login watcher 在跑

sudo docker exec -it xhs-novnc bash -lc "ps aux | grep login_watcher | grep -v grep"

3）手工触发一次登录（等价于 Web 按钮）

echo '{"ts":'$(date +%s)'}' | sudo tee ./data/.login_request.json > /dev/null

五、我们踩过的坑（必读）

1. Dockerfile 不能以 ENV 开头：必须先 FROM ...，否则报 no build stage / unknown instruction。
2. 把命令行记录误写进 Dockerfile：例如 cd /opt/xhs_cloud 会导致 unknown instruction: cd。
3. Docker Hub 拉取超时：docker compose up 会尝试 pull；本地已 build 时用 --pull never。
4. Playwright 缺失：web/novnc 镜像要基于 mcr.microsoft.com/playwright/python:* 或在镜像内 pip install playwright + playwright install。
5. headed 浏览器需要 XServer：在容器里 headless=False 必须配 Xvfb；noVNC 方案需要 DISPLAY=:99。
6. xvfb-run -a 的 display 不是 :99：会导致你在 noVNC 里看不到浏览器；正确做法是直接 export DISPLAY=:99。
7. noVNC 访问根路径只会看到目录列表：要访问 /vnc.html 或 /vnc_auto.html。
8. watcher 放在 tail -f /dev/null 后面永远不会执行：必须在 tail 之前启动。
9. 镜像更新但容器没更新：docker build 后要 docker compose up -d --force-recreate <service>，否则容器还在用旧 sha。
10. 端口混淆导致 curl 000：容器监听 8000，但宿主机映射可能是 28000；curl 要打宿主机端口。
11. 静态文件路径不对：页面实际在 /app/app/static/index.html，不是 /app/static。

六、升级/更新

• 更新代码后：

sudo docker build --provenance=false --no-cache -t xhs-cloud-web:stable -f Dockerfile .
sudo docker build --provenance=false --no-cache -t xhs-cloud-novnc:stable -f Dockerfile.novnc .
sudo docker compose up -d --pull never --force-recreate xhs-web xhs-novnc