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

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

## 端口约定（可改）
- Web：28000（容器 8000）
- noVNC：26080（容器 6080）
> 你们只开放 10000-50000 端口的话，把这两个端口改到范围内即可。

## 一、首次部署（非 1Panel）
```bash
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` 避免再拉取。
```bash
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）启动
```bash
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）确认端口映射
```bash
sudo docker port xhs-web
sudo docker port xhs-novnc
sudo ss -lntp | egrep "(:28000|:26080)\b"
```

### 2）确认 login watcher 在跑
```bash
sudo docker exec -it xhs-novnc bash -lc "ps aux | grep login_watcher | grep -v grep"
```

### 3）手工触发一次登录（等价于 Web 按钮）
```bash
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`。

## 六、升级/更新
- 更新代码后：
```bash
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
```