Sitemap Watch

游戏发现工作台：添加游戏站的 Sitemap，每日发现新增与移除，自动提取新增页标题和简介；在网页筛选、侧边展开详情、复制关键词和导出 CSV。

Python 3.12 + Flask + Neon PostgreSQL，本地也支持 SQLite。一个仓库、一个 Vercel 部署，不依赖 GitHub Actions 执行扫描。

本地启动

uv sync --frozen
uv run sitemap-watch serve --port 8768

打开 http://127.0.0.1:8768。配置写入项目根目录 .env.local，字段见 .env.example。若已配置 Neon 但想查看本地数据：

DATABASE_URL='' uv run sitemap-watch serve --port 8768

SQLite 默认仍是 data/sitemap_watch.sqlite3。应用不再启动旧定时线程；本机点击扫描，或执行 uv run sitemap-watch scan。旧命令 PYTHONPATH=src python -m sitemap_watch 转到同一个 Flask 入口，需先安装新依赖。

页面

• 变化清单：日期、来源、类型、搜索与提取状态；侧边详情、关键词复制；CSV 与当前筛选一致。
• 监控站点：多根 Sitemap，增删、编辑、暂停与恢复；路径推荐、预览和确认，正则兜底。
• 扫描历史：检查时间、成功、部分失败、保护状态。未完成扫描不展示成零变化。

只提供新增与移除，不检测旧页内容更新。首次只建基线；lastmod 仅参考；配置修改不产生网站变化事件。

每日扫描

Cron 为 UTC 17 1 * * *（计划北京时间 09:17，Hobby 可能在该小时内延迟）。每批约 240 秒，平台上限 300 秒。每域名串行、间隔至少五秒，遵守更长的 Crawl-delay。

到时保存进度，显示“待继续”；点击继续或下一次每日 Cron 接续。不会在请求结束后依赖后台线程。根与子 Sitemap 全部完成后才提交差异；暂存超过 24 小时重新获取。

每天触发不等于任意规模都能每天完整扫完。 大索引、多站点和大量新增可能需要多批。页面显示完整性与上次成功时间，须以实站耗时验收。重复 Cron 复用同日任务。

旧库的短间隔和默认 24 小时配置，都按北京时间自然日执行：今天尚未成功扫描即到期，不要求距昨天扫描满 24 小时。明确设置大于 24 小时的站点仍遵守自定义间隔。每次触发及跳过原因可在运行日志与扫描历史的每日调度记录中查看。手动扫描仍遵守限速、预算和冷却。

数据迁移

DATABASE_URL 连接 Neon。应用启动不自动建表；明确批准后才执行写入命令。

# 只列出迁移文件，不连接数据库
uv run sitemap-watch migrate
# 批准后执行建表
uv run sitemap-watch migrate --apply
# 只读检查源数据，不连接目标
uv run python scripts/migrate_sqlite.py --source data/sitemap_watch.sqlite3
# 批准后导入，目标业务表必须为空
uv run python scripts/migrate_sqlite.py --source data/sitemap_watch.sqlite3 --apply

导入使用一致性只读快照和 PostgreSQL COPY，事务内校验条数与 ID 序列。保留原 SQLite，不覆盖非空目标。切换时先停止旧扫描进程，避免继续写入旧库。

项目结构

app/                 Flask、页面、存储适配、扫描运行器
public/assets/       唯一 CSS / JavaScript 源文件
src/sitemap_watch/   解析、差异、规则、提取核心
migrations/          显式 PostgreSQL 建表脚本
scripts/             数据导入工具
tests/               本地回归与可选 PostgreSQL 集成测试
docs/                需求、部署与迁移说明
index.py             Vercel 入口
vercel.json          每日 Cron 与时限
uv.lock              可复现依赖

验证

uv run python -m unittest discover -s tests -q

默认测试使用临时 SQLite 和假 HTTP 响应，不访问游戏站；真实 PostgreSQL 测试默认跳过，需明确批准后提供专用 TEST_POSTGRES_URL。

当前约定见 需求 v1.2，上线步骤见 部署与迁移。GitHub 目标仓库：https://github.com/imshiwen/SitemapWatch。