chore: 项目定名为 workbuddy-portal，容器化并补齐文档体系
## 项目定名 - 目录 wb_usage_portal → workbuddy-portal - Python 包 wb_usage → workbuddy_portal（含 session cookie 名） - 界面品牌统一为 WorkBuddy Portal；项目标识收敛到 config 单一来源 ## 容器化 - Dockerfile：多阶段构建，依赖层与源码解耦；非 root(uid 1000)；内置健康检查 - docker-compose.yml：单服务 + 绑定挂载 data/logs + 日志轮转 + TZ - docker/entrypoint.sh：幂等初始化 → exec serve（LF 行尾，已由 .gitattributes 锁定） - docker/healthcheck.py：纯标准库探活 /login（slim 镜像无 curl） - .dockerignore / .env.example；数据目录可用 WB_DATA_DIR 等环境变量覆盖 ## 文档 - docs/USER-GUIDE.md 用户使用手册（含 9 张真实界面截图） - docs/DEPLOYMENT.md 部署运维（Docker / 裸机 / 反代 / 备份 / 推 Gitea 注册表） - docs/ARCHITECTURE.md 架构与设计说明（含已知坑与红线、验证体系） - docs/API.md 接口参考（路径 / 参数 / 返回结构 / 错误码） - docs/FAQ.md 常见问题；docs/CHANGELOG.md 变更日志 ## 修复缺陷（8） 1. /records/export 必然 500：生成器在请求上下文销毁后才迭代，改用自建连接 2. 大屏页图表全白：相对路径把 echarts.min.js 解析成 /vendor/... → 404 3. /users 500：路由已注册但模板缺失 4. 明细页日期筛选失效：视图传 f.frm、模板读 f.from 5. 配置页维护按钮全死：调用了不存在的 WBU.bindMaint() 6. 审计只能看最近 40 条：LIMIT 写死 7. 明细页多跑一条无用 SELECT：day_list() 取了没人用 8. 登录页锁定阈值未从配置注入 ## 安全加固 - 新增 safe_next()：拒绝 //evil.com 等协议相对 URL 的开放重定向 - 缺 CSRF 的写请求统一 400 - 默认开启云端 HTTPS 证书校验（ssl_verify=1）；Cookie 是账号凭证 - 登录失败计数表加上限与 TTL - /logout 拆分为 POST(执行) + GET(仅提示)，防 <img src=/logout> 静默退出 - settings 内部簿记键 slot:* 读写两侧过滤，不再从 /api/settings 泄漏 ## 内部质量与工具 - 设置项写时校验 + 读时兜底，杜绝「一个手滑的数字让采集整个跑不起来」 - 全局 ValueError → 400：手写 query string 不再暴露 500 页面 - CSV 导出改 csv.writer 流式写入（原手工拼串，字段含逗号会串列） - bundle 明细加 20000 上限并回传 recordsTotal/recordsTruncated，不静默丢数据 - tools/smoke.py 离线回归 99 项；tools/check_live.py 真实 HTTP 56 项 - tools/shots.py Playwright 逐页截图 + JS 报错收集 ## 验证 - compileall 通过；smoke 99/99；对容器实例 check_live 56/56；截图 0 JS 报错 - 容器内采集实测成功（trigger=startup 补跑：新增 11 条）
这个提交包含在：
@@ -0,0 +1,178 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
"""进程内调度器（手写，不依赖 APScheduler）。
|
||||
|
||||
为什么不引 APScheduler：
|
||||
* 需求只是「每天固定几个时刻跑一次」，一个线程 + 20 秒轮询足够
|
||||
* 需要「启动补跑」（程序没开的时候错过了时刻，开机后要补上）
|
||||
* 需要和 CLI 共享同一把文件锁，避免两处同时采集
|
||||
|
||||
单实例保证：
|
||||
* Flask 的 reloader 会 fork 两个进程 → 只在 WERKZEUG_RUN_MAIN 里启动
|
||||
* 多进程部署时用环境变量 WB_DISABLE_SCHEDULER=1 关掉除一个之外的所有实例
|
||||
* 真正防重复采集靠 collect._Lock（文件锁），即使两个调度线程同时触发也只会跑一个
|
||||
"""
|
||||
import logging
|
||||
import os
|
||||
import threading
|
||||
from datetime import datetime, timedelta
|
||||
|
||||
from . import collect, db
|
||||
|
||||
log = logging.getLogger("wb.scheduler")
|
||||
SLOT_PREFIX = "slot:" # settings 键：slot:09:00 -> 最近执行的日期
|
||||
|
||||
|
||||
def parse_times(raw):
|
||||
"""把 '09:00,17:00' 解析成 ['09:00','17:00']；非法片段直接丢弃。
|
||||
|
||||
对外公开（config.normalize_setting 用它做写入校验），所以不要改名。
|
||||
"""
|
||||
out = []
|
||||
for part in str(raw or "").replace("；", ",").replace("，", ",").split(","):
|
||||
p = part.strip()
|
||||
if not p:
|
||||
continue
|
||||
bits = p.split(":")
|
||||
try:
|
||||
hh = int(bits[0])
|
||||
mm = int(bits[1]) if len(bits) > 1 else 0
|
||||
except ValueError:
|
||||
continue
|
||||
if 0 <= hh <= 23 and 0 <= mm <= 59:
|
||||
out.append("%02d:%02d" % (hh, mm))
|
||||
return sorted(set(out))
|
||||
|
||||
|
||||
# 兼容旧名（早期版本用 _parse_times）
|
||||
_parse_times = parse_times
|
||||
|
||||
|
||||
def slots(conn):
|
||||
return parse_times(db.get_setting(conn, "schedule_times"))
|
||||
|
||||
|
||||
def last_run_of_slot(conn, slot):
|
||||
return db.get_setting(conn, SLOT_PREFIX + slot, "")
|
||||
|
||||
|
||||
def mark_slot(conn, slot, day):
|
||||
db.set_setting(conn, SLOT_PREFIX + slot, day)
|
||||
|
||||
|
||||
def next_run_at(conn, now=None):
|
||||
"""下一次计划执行时间（仅按配置推算，不含补跑）。"""
|
||||
if not db.get_bool(conn, "schedule_enabled", True):
|
||||
return None
|
||||
now = now or datetime.now()
|
||||
best = None
|
||||
for s in slots(conn):
|
||||
hh, mm = map(int, s.split(":"))
|
||||
cand = now.replace(hour=hh, minute=mm, second=0, microsecond=0)
|
||||
if cand <= now:
|
||||
cand += timedelta(days=1)
|
||||
if best is None or cand < best:
|
||||
best = cand
|
||||
return best
|
||||
|
||||
|
||||
def due_slots(conn, now=None):
|
||||
"""返回此刻应当执行的槽位列表（含启动补跑）。"""
|
||||
if not db.get_bool(conn, "schedule_enabled", True):
|
||||
return []
|
||||
now = now or datetime.now()
|
||||
today = now.strftime("%Y-%m-%d")
|
||||
# 用 get_int 兜底：catch_up_grace_hours 在后台是自由文本框，
|
||||
# 历史上填成 "12h" 会让这里 int() 抛 ValueError，把 /tasks 打成 500。
|
||||
grace_hours = db.get_int(conn, "catch_up_grace_hours", 12)
|
||||
grace = timedelta(hours=max(1, grace_hours))
|
||||
catch_up = db.get_bool(conn, "catch_up", True)
|
||||
out = []
|
||||
for s in slots(conn):
|
||||
hh, mm = map(int, s.split(":"))
|
||||
when = now.replace(hour=hh, minute=mm, second=0, microsecond=0)
|
||||
if when > now:
|
||||
continue # 还没到点
|
||||
if last_run_of_slot(conn, s) == today:
|
||||
continue # 今天这个槽位已跑过
|
||||
if when < now - grace and catch_up:
|
||||
continue # 错过太久，不补（避免开机狂刷）
|
||||
if when < now - timedelta(seconds=90) and not catch_up:
|
||||
continue # 未开启补跑，只认刚到的点
|
||||
out.append(s)
|
||||
return out
|
||||
|
||||
|
||||
class Scheduler:
|
||||
def __init__(self, interval=20):
|
||||
self.interval = interval
|
||||
self._stop = threading.Event()
|
||||
self._thread = None
|
||||
|
||||
# ---- 生命周期 ----
|
||||
def start(self):
|
||||
if self._thread and self._thread.is_alive():
|
||||
return False
|
||||
self._stop.clear()
|
||||
self._thread = threading.Thread(target=self._loop, name="wb-scheduler", daemon=True)
|
||||
self._thread.start()
|
||||
log.info("调度器已启动，轮询间隔 %ss", self.interval)
|
||||
return True
|
||||
|
||||
def stop(self):
|
||||
self._stop.set()
|
||||
if self._thread:
|
||||
self._thread.join(timeout=5)
|
||||
|
||||
@property
|
||||
def running(self):
|
||||
return bool(self._thread and self._thread.is_alive())
|
||||
|
||||
# ---- 主循环 ----
|
||||
def _loop(self):
|
||||
while not self._stop.is_set():
|
||||
try:
|
||||
self.tick()
|
||||
except Exception as e: # 任何异常都不能让线程死掉
|
||||
log.exception("调度 tick 出错：%s", e)
|
||||
self._stop.wait(self.interval)
|
||||
|
||||
def tick(self, now=None):
|
||||
conn = db.thread_conn()
|
||||
now = now or datetime.now()
|
||||
today = now.strftime("%Y-%m-%d")
|
||||
for slot in due_slots(conn, now):
|
||||
scheduled = now.replace(hour=int(slot[:2]), minute=int(slot[3:]),
|
||||
second=0, microsecond=0)
|
||||
trigger = "startup" if now - scheduled > timedelta(minutes=5) else "schedule"
|
||||
log.info("触发采集：槽位 %s（%s）", slot, trigger)
|
||||
mark_slot(conn, slot, today) # 先占位，避免采集失败被无限重试打爆云端
|
||||
try:
|
||||
r = collect.run_sync(trigger=trigger)
|
||||
log.info("采集完成：%s", r["message"])
|
||||
except collect.Busy as e:
|
||||
log.warning("跳过（%s）", e)
|
||||
except Exception as e:
|
||||
log.error("采集失败：%s", e)
|
||||
return True
|
||||
|
||||
|
||||
_scheduler = None
|
||||
|
||||
|
||||
def get_scheduler(interval=20):
|
||||
global _scheduler
|
||||
if _scheduler is None:
|
||||
_scheduler = Scheduler(interval=interval)
|
||||
return _scheduler
|
||||
|
||||
|
||||
def start_from_app(app):
|
||||
"""由 create_app 调用。遵守 reloader 与显式禁用开关。"""
|
||||
if os.environ.get("WB_DISABLE_SCHEDULER") == "1":
|
||||
app.logger.info("WB_DISABLE_SCHEDULER=1，调度器未启动")
|
||||
return None
|
||||
if app.debug and os.environ.get("WERKZEUG_RUN_MAIN") != "true":
|
||||
return None # reloader 的父进程不启动，避免跑两份
|
||||
sch = get_scheduler()
|
||||
sch.start()
|
||||
return sch
|
||||
在新工单中引用
屏蔽一个用户