--- name: wechat-viewer-ops description: WeChat Viewer 运维操作——启动/重启、反向代理(Cloudflare Tunnel)、登录认证、端口管理。 version: 1.0 category: wechat --- # WeChat Viewer 运维手册 ## 端口 app.py 硬编码端口 **5001**(config.py 里写的 5000 是假的,不要信)。 ## 启动 ```bash cd ~/wechat-viewer && python3 -B app.py ``` `-B` 禁止 pycache,避免改代码后缓存旧版。 ### 后台运行 ```bash cd ~/wechat-viewer && python3 -B app.py & ``` ### 重启 ```bash # 1. 找 PID(Termux 下 fuser 不管用,必须 su) su -c "netstat -tlnp 2>/dev/null | grep 5001" # 2. 杀进程 su -c "kill -9 " # 3. 确认端口释放 fuser 5001/tcp 2>/dev/null || echo "free" # 4. 重新启动 cd ~/wechat-viewer && python3 -B app.py & ``` ## 登录认证 认证系统在 app.py 中,基于 Flask session(client-side 签名 cookie)。 ### 架构 ``` before_request → 检查 session['user_id'] ├─ 有 → 放行 └─ 无 → redirect /login?next=<原路径> 白名单: /login, /logout, /static ``` ### 用户管理 users 表在 local_db.py 的 init_db() 中创建: ```sql CREATE TABLE IF NOT EXISTS users ( id INTEGER PRIMARY KEY AUTOINCREMENT, username TEXT UNIQUE NOT NULL, password_hash TEXT NOT NULL, created_at TEXT DEFAULT (datetime('now','localtime')) ); ``` 密码使用 SHA-256 哈希存储。 默认账号:**admin / wechat2026** ### 手动添加用户 ```python import hashlib, local_db pw = hashlib.sha256("password".encode()).hexdigest() conn = local_db.get_conn() conn.execute("INSERT OR IGNORE INTO users (username, password_hash) VALUES (?, ?)", ("user", pw)) conn.commit() ``` ### Pitfalls - **Client-side session**:logout 后旧 cookie 仍可访问(解密后 session 数据还在 cookie 里)。真实浏览器会接受 logout 返回的空 Set-Cookie 替换旧 cookie。测试时需模拟浏览器行为(logout 后用无 cookie 请求验证)。 - **secret_key 随机**:`app.secret_key = os.urandom(24)` 每次进程重启都变,所有旧 session 失效。重启后用户需重新登录。 ## 反向代理(Cloudflare Tunnel) ### 安装 ```bash pkg update && pkg install -y cloudflared ``` Termux 仓库自带,aarch64 架构支持。 ### Quick Tunnel(零配置) ```bash cloudflared tunnel --url http://localhost:5001 ``` 输出 `https://<随机>.trycloudflare.com`。 ### ⚠️ 隧道静默挂掉(2026-08-07 实战;**2026-10-06 已更新:看门狗现在管隧道了**) **看门狗已接管隧道巡检(2026-10-06 核对源码为准)**:`~/pixelphone/scripts/wechat-viewer-watchdog.sh` 尾部(§112-141)除 Flask 5001 / Gateway / 微信 Watcher 外,**也检 cloudflared**: ① 进程不在就拉起;② 进程在也**实测公网端点** `curl -sS -m 8 https://task.hexdo.com/api/doctor`,非 200/302 即 `pkill` + 重启隧道(重启后复测,日志落在 `~/wechat-viewer/watchdog.log`)。 调度 = hermes cron job `9d42ea7f523a`,「WeChat Viewer 看门狗」**interval 10 分钟**(实测有漂移到 13 分钟)。 **判读公网 502/530/000 的正确姿势(2026-10-06 11:00 轮实测,血泪)**: - **别看单次读数**:11:02 读到 502/530、11:03:4x 自动恢复 200、11:08 又 530、11:16 再自愈 —— 一个 15 分钟窗口里三态轮转。单次非 200 **不能**判「隧道/日报挂了」。 - **定因两问**:① `su -c "ps -ef | grep -i cloudflared | grep -v grep"` 看 **pid 是否刚换过**(换了 = 看门狗刚重启过);② `tail -c 1000 ~/wechat-viewer/watchdog.log` 找最近的「探测异常(...) → 重启隧道 → 隧道重启后恢复」三连行。 - ⚠️ **watchdog.log 的日期是 `date` 默认格式**(`Tue Oct 6 11:16:31 CST 2026`),**不是 ISO** —— 用 `2026-10-06 11` 去 grep **恒零命中**,会误判「日志里什么都没有」。 - **本地 `:5001` 全程 200 + 公网间歇 530** = 隧道侧问题,不是 Flask 问题(别去重启 Flask)。 - 530 是 Cloudflare 真返回的状态码(tunnel 未连通),**不是** IPv6 假阴性(后者表现为 000;见下节 `-4` 坑)。当日 4 次掉线(00:01 / 00:47 / 11:03 / 11:16)全部自愈,**锁屏/Doze 期偏高**(假说,未证)。 - **3MB 级 HTML 走手机上行会慢**:8s 超时的 curl 常见「收到部分字节后超时」(实测收到 10KB~2.4MB),**浏览器侧通常仍能打开**,别据此判死链。 **检测**: ```bash su -c "ps -ef | grep -i cloudflared | grep -v grep" # 空 = 隧道进程挂了 curl -4 -s -o /dev/null -w '%{http_code}' https://task.hexdo.com/api/doctor # 非 302/200 = 挂了 ``` ### ⚠️⚠️ 检测必须加 `-4`(2026-09-20 02:00 轮实测,假故障源头) 本机 DNS 同时返回 A 与 AAAA,而 **IPv6 出口不通**(`curl -6` 0.46s 即失败),curl 默认优先 AAAA ⇒ `curl https://task.hexdo.com/...` 连续 **HTTP 000 超时**(实测 25s/60s/90s/150s 全超时,连 google/cloudflare.com 也 000),极易误判成「tunnel 挂了 / 公网链接失效」,进而白跑一遍排错甚至误报故障。 同一时刻的对照: ```bash curl -4 -s -o /dev/null -w '%{http_code} %{time_total}\n' https://task.hexdo.com/ # 302, 2.3s curl -4 -s -o /dev/null -w '%{http_code} %{size_download}\n' https://task.hexdo.com/digest/tgo/2026-09-19 # 200, 2765875B, 4.1s ``` **铁律:本机做任何公网可达性校验一律 `curl -4`**(watchdog 里的公网实测、日报 HTML 公网验收、隧道健康检查全都适用)。判定「隧道是否活」的权威依据仍是 `~/.cloudflared/tunnel.log` 里的 `Registered tunnel connection`(4 条 connection = 正常)。 ### 检测隧道健康时不要被 cloudflared 自身日志吓到 `tunnel.log` 里 `precheck ... hard_fail=true` / `TLS handshake with edge ... i/o timeout` / `Connection terminated` 是**边缘节点抖动 + 自动重连**的常态噪声——只要随后出现 `Registered tunnel connection connIndex=N`,隧道就是好的(2026-09-20 实测:QUIC 与 region2 全 fail、仍成功注册 4 条 http2 connection,公网访问 200)。不要因为有 ERR 行就重启隧道。 **恢复**(Quick Tunnel 模式): ```bash cd ~ && nohup cloudflared tunnel --url http://localhost:5001 --no-autoupdate > ~/.cloudflared/tunnel.log 2>&1 & # 新 URL 在日志里:grep trycloudflare ~/.cloudflared/tunnel.log ``` **Quick Tunnel URL 每次重启都变**(随机域名),旧链接全部失效——有固定地址需求必须配正式 Tunnel。`~/.cloudflared/` 为空 = 纯 Quick Tunnel 模式,无正式域名配置。 ### 正式 Tunnel(绑定域名) ```bash cloudflared tunnel login # 浏览器授权 cloudflared tunnel create wechat-viewer cloudflared tunnel route dns wechat-viewer wechat.your-domain.com cloudflared tunnel run wechat-viewer --url http://localhost:5001 ``` ### 正式 Tunnel 凭证丢失恢复(2026-08-07 实战,task.hexdo.com) `~/.cloudflared/` 被清空(cert.pem + credentials 都没了)后的恢复路径: 1. `cloudflared tunnel login` → 打印授权 URL → 手机浏览器打开(`am start -a android.intent.action.VIEW -d ""`)→ 登录 Cloudflare 选域名授权 2. 回调 `login.cloudflareaccess.org` 可能被墙、cert.pem 落不下来 → 可在其他机器(如 Mac)完成授权,把 `.json` credentials 拷回手机 3. **run 只需要 credentials json + config.yml,不需要 cert.pem**——cert.pem 只用于 create / route dns 操作。手机上有 `~/.cloudflared/.json` + config.yml(ingress: hostname 指向 127.0.0.1:5001 + catch-all `http_status:404`)就能 `cloudflared tunnel --config ~/.cloudflared/config.yml run ` 长期跑 4. 多域名 = 多条独立 tunnel(task.hexdo.com 在手机、bridge.hexdo.com 在 Mac),互不影响 ### Pitfalls - `cloudflared tunnel login` 可能连不上回调地址(被墙),浏览器授权后需手动 `cp cert.pem ~/.cloudflared/cert.pem` - **隧道进程 uid 坑 → watchdog 无限重启**:root 启动的 cloudflared,Termux 用户 `pgrep -f` 看不到 → 看门狗以为死了每次 tick 又拉一个 → 进程堆积。**必须以 Termux 用户 uid 跑隧道**(普通 nohup,不要 su)。2026-08-07 实战修复:`su -G 3003 ` 重启 + 同步文件属主 - **看门狗正确模式(2026-08-07 已实现在 watchdog 第 7 段)**:进程检查(pgrep `cloudflared tunnel --config.*`)+ **公网端点实测**(`curl https://<域名>/api/doctor` 返回 200 才算通,进程活着≠隧道通)+ 异常重启一次 + 仍失败打诊断行。配合 cron `no_agent: true`:正常静默、故障 stdout 直接推微信,无需新发送机制 - **残留凭据导致 Quick Tunnel 404**:之前 login 生成的 `~/.cloudflared/cert.pem` 和 `~/.cloudflared/config.yml` 会干扰 Quick Tunnel,导致连接成功但访问返回 Cloudflare 404。修复:`rm -f ~/.cloudflared/cert.pem ~/.cloudflared/config.yml` 后重新创建 tunnel(2026-07-31 实战验证) - **api.trycloudflare.com 可能被墙**:Quick Tunnel 的 API endpoint 可能间歇性不可达(HTTP 000),换网络或等恢复。正式 Tunnel 的 `api.cloudflare.com` 更稳定 - 公网暴露后务必启用登录保护(否则任何人可查看微信消息) ## 简历管理页 - Route: `/resumes` — 列表页,含搜索/岗位筛选/分档筛选/排序,**含状态列**(点击 badge 弹出下拉菜单切换) - Route: `/resume/` — 详情页。**原始 JSON 数据必须默认可见**(不用 `
` 折叠),放在经历列表之前 - API: `PATCH /api/resumes//status` — 更新简历状态(待面试/已面试/已淘汰/已入职) - 状态下拉菜单:点击 badge → 弹出选择 → PATCH 更新 → 即时渲染。⚠️ `
` 必须被 `` 包裹(badge 和 menu 都是该 wrapper 的子元素),否则 `position:absolute;top:100%` 相对于 td 或 body 定位,menu 不显示(2026-07-31 实战 bug) ### Resume DB Schema 同步(关键陷阱) `import_resumes.py` 的 CREATE TABLE 必须与 `app.py` 的 SELECT 列保持同步。**每次 ALTER TABLE 加列后须同步更新 import 脚本**: 1. `import_resumes.py` CREATE TABLE 加列 2. `import_resumes.py` INSERT 加列和占位符(count 断言同步更新) 3. 现有 DB 执行 `ALTER TABLE resumes ADD COLUMN` 当前表完整列:id, friendId, name, jobPosition, jobId, age, education, **gender**, applyStatus, city, expSalary, workAge, firstText, secondText, positionName, jobSalary, **status**, experiences, raw_json, imported_at ⚠️ BOSS简历管理 cron 每 6 小时运行一次导入流程。缺列会导致 `/api/resumes` 返回 500 (`no such column`)。2026-08-01 实战:gender 和 status 两列同时丢失。 ## 一体启动脚本 ```bash #!/bin/bash # ~/wechat-viewer/restart.sh cd ~/wechat-viewer # 杀掉旧进程 OLD_PID=$(su -c "netstat -tlnp 2>/dev/null | grep 5001" | awk '{print $NF}' | cut -d/ -f1) [ -n "$OLD_PID" ] && su -c "kill -9 $OLD_PID" 2>/dev/null sleep 1 # 启动 Flask python3 -B app.py & # 启动隧道(可选) # cloudflared tunnel --url http://localhost:5001 & ``` ## 日报静态 HTML(/digest,2026-08-08) 日报现在产出**静态 HTML**(带文章链接),公网地址 `https://task.hexdo.com/digest/`,注册用户登录后可看(admin/user 均可,见 wechat-viewer-dev「注册与权限分层」)。 - **产物**:`~/wechat-viewer/digests/digest_.html`,由 `gen_digest_html.py` 生成(python-markdown 服务端渲染,脚本在 wechat-group-digest skill scripts;命令 `gen_digest_html.py --date YYYY-MM-DD`) - **路由**:`/digest/` → `send_file` + 正则 `\d{4}-\d{2}-\d{2}` 校验日期防路径穿越 - ⚠️ **文件必须放 `digests/` 目录而不是 `/static/`**——/static 在登录白名单里(`AUTH_WHITELIST`),放 static 会绕过权限裸奔 - **列表页入口**:/reports 每行 digest 有紫色「HTML版」按钮(#8e44ad),由 `/api/reports` 返回的 `html_exists` 字段控制——只有对应 html 文件存在才显示按钮 - **详情页入口**:/report/ 的 nav 有「📄 HTML版」链接(JS 按 `report_date` 动态加,非 digest 日期不显示) - **图片二维码**:`add_qr_to_image.py`(gpt-image-gen skill scripts)→ 二维码内容 = `https://task.hexdo.com/digest/`,贴右下角白卡片 - **验证注意**:列表页是 JS 动态渲染(`render()` 拼 `/digest/'+rp.report_date`),curl 服务器源码**看不到**具体 /digest/ 链接——验证要看 `/api/reports` 的 html_exists 字段或浏览器渲染 ## 日报图片生成 参见 `references/daily-image-script.md`。