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,156 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
"""SQLite 访问层。
|
||||
|
||||
并发约定（重要）：
|
||||
* WAL 模式 —— 采集写入期间页面查询不会被 `database is locked` 挡住
|
||||
* 单写者 —— SQLite 同一时刻只允许一个写进程，所以采集必须串行
|
||||
（由 scheduler / CLI 共享的 collect.lock 保证）
|
||||
* busy_timeout=8s —— 偶发并发时等待而不是立刻报错
|
||||
* 每个线程独立连接（sqlite3 默认禁止跨线程复用连接）
|
||||
"""
|
||||
import os
|
||||
import sqlite3
|
||||
import threading
|
||||
from datetime import datetime
|
||||
|
||||
from . import config
|
||||
|
||||
_local = threading.local()
|
||||
_init_lock = threading.Lock()
|
||||
_initialized = False
|
||||
|
||||
|
||||
def now_str():
|
||||
return datetime.now().strftime("%Y-%m-%d %H:%M:%S")
|
||||
|
||||
|
||||
def connect(path=None):
|
||||
"""新建一个连接（调用方负责关闭）。"""
|
||||
config.ensure_dirs()
|
||||
conn = sqlite3.connect(path or config.SQLITE_PATH, timeout=8.0,
|
||||
isolation_level=None) # autocommit，事务用显式 BEGIN
|
||||
conn.row_factory = sqlite3.Row
|
||||
conn.execute("PRAGMA journal_mode=WAL")
|
||||
conn.execute("PRAGMA synchronous=NORMAL")
|
||||
conn.execute("PRAGMA busy_timeout=8000")
|
||||
conn.execute("PRAGMA foreign_keys=ON")
|
||||
return conn
|
||||
|
||||
|
||||
def thread_conn():
|
||||
"""按线程缓存的连接（采集线程、调度线程各自一份）。"""
|
||||
c = getattr(_local, "conn", None)
|
||||
if c is None:
|
||||
c = _local.conn = connect()
|
||||
return c
|
||||
|
||||
|
||||
def close_thread_conn():
|
||||
c = getattr(_local, "conn", None)
|
||||
if c is not None:
|
||||
try:
|
||||
c.close()
|
||||
except sqlite3.Error:
|
||||
pass
|
||||
_local.conn = None
|
||||
|
||||
|
||||
# ---------------- 初始化 ----------------
|
||||
def init_db(conn=None, create_admin=True, admin_user="admin", admin_password=None):
|
||||
"""建表 + 灌默认配置。可重复执行（幂等）。"""
|
||||
global _initialized
|
||||
own = conn is None
|
||||
conn = conn or connect()
|
||||
try:
|
||||
with open(os.path.join(os.path.dirname(os.path.abspath(__file__)), "schema.sql"),
|
||||
"r", encoding="utf-8") as f:
|
||||
conn.executescript(f.read())
|
||||
# 默认配置（不覆盖已有值）
|
||||
ts = now_str()
|
||||
for k, v in config.DEFAULTS.items():
|
||||
conn.execute("INSERT OR IGNORE INTO settings(key,value,updated_at) VALUES(?,?,?)",
|
||||
(k, v, ts))
|
||||
if create_admin:
|
||||
n = conn.execute("SELECT COUNT(*) FROM users").fetchone()[0]
|
||||
if n == 0:
|
||||
from .security import hash_password
|
||||
pwd = admin_password or "admin123"
|
||||
conn.execute(
|
||||
"INSERT INTO users(username,password_hash,display_name,is_admin,created_at)"
|
||||
" VALUES(?,?,?,1,?)", (admin_user, hash_password(pwd), "管理员", ts))
|
||||
_initialized = True
|
||||
finally:
|
||||
if own:
|
||||
conn.close()
|
||||
|
||||
|
||||
# ---------------- 配置读写 ----------------
|
||||
def get_setting(conn, key, default=None):
|
||||
row = conn.execute("SELECT value FROM settings WHERE key=?", (key,)).fetchone()
|
||||
if row is None or row["value"] is None:
|
||||
return config.DEFAULTS.get(key, default)
|
||||
return row["value"]
|
||||
|
||||
|
||||
def get_settings(conn, keys=None):
|
||||
rows = conn.execute("SELECT key,value FROM settings").fetchall()
|
||||
got = {r["key"]: r["value"] for r in rows}
|
||||
out = dict(config.DEFAULTS)
|
||||
out.update(got)
|
||||
if keys:
|
||||
return {k: out.get(k) for k in keys}
|
||||
return out
|
||||
|
||||
|
||||
def set_setting(conn, key, value):
|
||||
conn.execute("INSERT INTO settings(key,value,updated_at) VALUES(?,?,?) "
|
||||
"ON CONFLICT(key) DO UPDATE SET value=excluded.value, updated_at=excluded.updated_at",
|
||||
(key, "" if value is None else str(value), now_str()))
|
||||
|
||||
|
||||
def set_settings(conn, pairs):
|
||||
for k, v in pairs.items():
|
||||
set_setting(conn, k, v)
|
||||
|
||||
|
||||
def get_int(conn, key, default=0):
|
||||
try:
|
||||
return int(float(get_setting(conn, key, default)))
|
||||
except (TypeError, ValueError):
|
||||
return default
|
||||
|
||||
|
||||
def get_float(conn, key, default=0.0):
|
||||
try:
|
||||
return float(get_setting(conn, key, default))
|
||||
except (TypeError, ValueError):
|
||||
return default
|
||||
|
||||
|
||||
def get_bool(conn, key, default=False):
|
||||
v = str(get_setting(conn, key, "1" if default else "0")).strip().lower()
|
||||
return v in ("1", "true", "yes", "on", "是")
|
||||
|
||||
|
||||
# ---------------- 审计 ----------------
|
||||
def audit(conn, action, actor=None, detail=None, ip=None):
|
||||
conn.execute("INSERT INTO audit_log(at,actor,action,detail,ip) VALUES(?,?,?,?,?)",
|
||||
(now_str(), actor, action, detail, ip))
|
||||
|
||||
|
||||
# ---------------- Flask 集成 ----------------
|
||||
def get_db():
|
||||
from flask import g
|
||||
if "db" not in g:
|
||||
g.db = connect()
|
||||
return g.db
|
||||
|
||||
|
||||
def close_db(exc=None):
|
||||
from flask import g
|
||||
db = g.pop("db", None)
|
||||
if db is not None:
|
||||
try:
|
||||
db.close()
|
||||
except sqlite3.Error:
|
||||
pass
|
||||
在新工单中引用
屏蔽一个用户