SKILL.md 12.6 KB

name: wechat-viewer-ops description: WeChat Viewer 运维操作——启动/重启、反向代理(Cloudflare Tunnel)、登录认证、端口管理。 version: 1.0

category: wechat

WeChat Viewer 运维手册

端口

app.py 硬编码端口 5001(config.py 里写的 5000 是假的,不要信)。

启动

cd ~/wechat-viewer && python3 -B app.py

-B 禁止 pycache,避免改代码后缓存旧版。

后台运行

cd ~/wechat-viewer && python3 -B app.py &

重启

# 1. 找 PID(Termux 下 fuser 不管用,必须 su)
su -c "netstat -tlnp 2>/dev/null | grep 5001"
# 2. 杀进程
su -c "kill -9 <PID>"
# 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() 中创建:

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

手动添加用户

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)

安装

pkg update && pkg install -y cloudflared

Termux 仓库自带,aarch64 架构支持。

Quick Tunnel(零配置)

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),浏览器侧通常仍能打开,别据此判死链。

检测:

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 挂了 / 公网链接失效」,进而白跑一遍排错甚至误报故障。

同一时刻的对照:

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 模式):

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(绑定域名)

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 "<url>")→ 登录 Cloudflare 选域名授权
  2. 回调 login.cloudflareaccess.org 可能被墙、cert.pem 落不下来 → 可在其他机器(如 Mac)完成授权,把 <tunnel-id>.json credentials 拷回手机
  3. run 只需要 credentials json + config.yml,不需要 cert.pem——cert.pem 只用于 create / route dns 操作。手机上有 ~/.cloudflared/<tunnel-id>.json + config.yml(ingress: hostname 指向 127.0.0.1:5001 + catch-all http_status:404)就能 cloudflared tunnel --config ~/.cloudflared/config.yml run <name> 长期跑
  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 <uid> 重启 + 同步文件属主
  • 看门狗正确模式(2026-08-07 已实现在 watchdog 第 7 段):进程检查(pgrep cloudflared tunnel --config.*<name>)+ 公网端点实测(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/<id> — 详情页。原始 JSON 数据必须默认可见(不用 <details> 折叠),放在经历列表之前
  • API: PATCH /api/resumes/<id>/status — 更新简历状态(待面试/已面试/已淘汰/已入职)
  • 状态下拉菜单:点击 badge → 弹出选择 → PATCH 更新 → 即时渲染。⚠️ <div class="status-menu"> 必须被 <span style="position:relative;display:inline-block"> 包裹(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 两列同时丢失。

一体启动脚本

#!/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/<YYYY-MM-DD>,注册用户登录后可看(admin/user 均可,见 wechat-viewer-dev「注册与权限分层」)。

  • 产物:~/wechat-viewer/digests/digest_<date>.html,由 gen_digest_html.py 生成(python-markdown 服务端渲染,脚本在 wechat-group-digest skill scripts;命令 gen_digest_html.py --date YYYY-MM-DD)
  • 路由:/digest/<date> → 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/<date>,贴右下角白卡片
  • 验证注意:列表页是 JS 动态渲染(render() 拼 /digest/'+rp.report_date),curl 服务器源码看不到具体 /digest/ 链接——验证要看 /api/reports 的 html_exists 字段或浏览器渲染

日报图片生成

参见 references/daily-image-script.md。