larablog/docs/specs/larablog-platform/SPEC.md

LaraBlog 平台一期

状态

• 状态：已定稿
• 创建：2026-08-11 17:14
• 最近更新：2026-08-11 17:53

背景

SaBlog-X 1.6（约二十年前设计）需迁移到现代 Laravel 栈。迁移目标不是「功能克隆」，而是：保留有价值的内容、SEO 权重与核心写作/阅读体验，用当代博客实践替换过时、产垃圾或维护成本不合理的设计。

参考源：https://github.com/neatstudio/sablog-archive

现代化取舍原则

1. 内容与 SEO 优先：文章/分类/标签 ID 与关键旧 URL 保留，避免权重归零
2. 不迁垃圾协议与死技术：Trackback/Pingback、WAP、旧 searchindex、旧 PHP Admin、Feedsky 等一律不实现
3. 用当代能力替换：AI 评论审核代替巨型敏感词表为主力；对象存储代替本地附件目录；Workerman 承载 LLM；Filament 后台
4. 导入可跳过废弃表：sablog_trackbacks / sablog_trackbacklog / sablog_searchindex / sablog_sessions 等只记录「已跳过」，不入新库
5. 旧入口若被爬虫打到：对明确废弃路径返回 410 Gone（不实现业务）

目标

• 可运行的现代博客：前台阅读/评论/搜索/归档 + Filament 5 后台
• 严格兼容 sablog 内容向伪静态与关键 query URL；导入后文章/分类 ID 一致
• 多主题、插件框架、SEO/GEO、S3 兼容附件、Workerman AI 运行时
• sablog:import：内容与附件上云；跳过过时模块并报告

范围

In scope

1. Laravel 12 + Livewire 4 + Filament 5 + Spatie（permission、settings、feed、sitemap、activitylog）
2. 博客核心：文章、分类、标签、评论、附件、友情链接、用户/角色、站点片段（stylevars）
3. Legacy 内容 URL + 新 canonical（见 URL 矩阵）
4. 主题引擎 + default + 示例主题（主题 zip 存本地 themes/）
5. 插件框架 + payment / membership / plugin-marketplace / theme-marketplace（骨架）+ ai-comment-moderation（可运行管道）
6. SEO/GEO：meta、OG、JSON-LD、sitemap、rss（含 ?cid）、llms.txt
7. 对象存储附件全链路 + legacy /attachment.php 与 /attachments/{path}
8. Workerman：ai-content、ai-moderation
9. sablog:import 幂等 upsert + 跳过废弃表报告
10. 防刷：rate limit；XSS purifier；附件 MIME 白名单
11. 可选现代增强：文章 slug（不取代 /show-{id}.shtml）
12. 正文格式双轨：content_format = html|markdown；站点默认新作为 Markdown；导入默认保留 HTML；可选 HTML→Markdown 转换开关

Out of scope（明确不迁移 / 不复刻）

• Trackback / Pingback（含表、后台、前台、开启开关）；/tburl.php、/trackback.php 仅 410
• WAP、旧 searchindex 搜索缓存表、自建 sessions 表、Feedsky/旧 JS 挂件
• 旧 /admin/* PHP 后台原样兼容（新后台 Filament /admin；旧路径 410）
• 旧主题静态 /templates/default/* 原样托管
• 真实支付/会员计费/远程商城结算；多站点 SaaS
• Workerman 替代主站 HTTP；绑定单一 LLM 厂商；应用侧长期存附件
• 以巨型政治/广告敏感词表为唯一防垃圾手段（可保留极简词表作预过滤，主力为 AI + rate limit）

延期（二期+，本期只预留）

自动配图 / 由正文生成封面（老 sablog 无现代「特色图」概念）：

• 能力意向：
  1. 自动配图：从正文首图 / 附件图 / OG 候选中选封面
  2. 生成配图：用标题+摘要（或 LLM 提示）调用文生图 / 模板渲染，产出封面，写入对象存储
• 执行方式：Workerman / 队列 Job + 可重跑 Artisan 脚本，批量慢生成，不堵发布主路径
• 本期只做：表字段与状态枚举预留、GenerateArticleCoverJob 空壳、SPEC/清单占位；不做真实选图/生图对接
• 封面文件同样只存对象存储，规则同附件

方案要点

技术栈

层	选型
框架	Laravel 12、PHP 8.2+、Livewire 4
后台	Filament 5
Spatie	permission、settings、feed、sitemap、activitylog
附件	自建 attachments + S3 disk（不用 medialibrary）
AI	Workerman + Redis；LlmProvider（OpenAI 兼容 + Stub）
净化 / 图	mews/purifier；Intervention Image（临时处理后退对象存储）

数据模型

• articles：id、category_id、user_id、title、content、content_format(html|markdown)、description、keywords、slug(nullable)、published_at、views、comments_count、stick、visible、close_comment、read_password(nullable，兼容旧私密文)、ai_summary、ai_suggestions、legacy_attachments、cover_*（二期配图预留，见下）
• 封面预留字段：cover_disk、cover_path、cover_source（none|manual|attachment|content_image|generated）、cover_status（none|pending|ready|failed）、cover_generated_at
• 无 trackbacks 表；无 close_trackback / trackbacks_count

正文格式（HTML / Markdown）

• 原则：旧 sablog 正文是 HTML；新写作默认 Markdown（未来主路径）
• 文章级开关：articles.content_format；后台编辑器按格式切换（Markdown 文本域 / HTML 富文本）
• 导入双模式（两份能力，同一命令开关）：
  1. raw（默认）：正文保持 HTML，content_format=html，保留 sablog [attach=id]
  2. markdown：HTML→Markdown，content_format=markdown；因 [] 是 Markdown 保留字符，导入时把 [attach=id] 改写成 Markdown 安全引用，不把对象存储 URL 写进库
• 附件引用策略（已定）：

  场景	数据库保存	预览/前台输出
  raw/HTML	[attach=123]（原样）	渲染期解析为 <img>/<a>，href/src 用稳定入口 /attachment.php?id=123（再 302 到 S3）
  markdown	图片 ；文件 [name](attach:123)	CommonMark 后把 attach:123 换成 /attachment.php?id=123

• 不在导入时写死 S3/CDN 路径：避免换桶/换域名后正文失效；平时 DB 只存引用，输出时转换
• 站点设置：default_content_format=markdown；导入模式由 CLI --mode=raw|markdown 决定（可覆盖 settings）
• 渲染：ContentRenderer::toHtml() = 格式转换 + attach 水合 + Purifier
• categories、comments（moderation_status：pending|pending_ai|approved|rejected|needs_human）、tags + article_tag、attachments、links、stylevars、plugins、users（password + password_legacy）
• Settings：站点、SEO、active_theme、LLM、存储、正文格式默认/导入策略（无 trackback_enabled）

导入映射（摘要）

源	目标	规则
articles 核心字段	articles.*	保留 id/cid/uid/views/close_comment/read_password 等
articles.content	content + content_format	默认 html；若开启转换则转为 Markdown 且 format=markdown
articles.trackbacks / closetrackback	—	忽略
articles.attachments serialize	legacy_attachments + attachments 表	文件上云
comments.visible	moderation_status	1→approved，0→pending
tags.aids	article_tag	拆 pivot
users.password	password_legacy	无盐 MD5 → 登录升级 bcrypt
attachments.*	attachments.*	逐条上云，保留 downloads
links / stylevars / settings	对应表/Settings	直通或键映射
sablog_trackbacks / trackbacklog / searchindex / sessions	—	跳过并计入报告

附件与对象存储

• 一律 S3 兼容；临时文件用完即删
• /attachment.php?id=、/attachments/{path} → 去重计数后 302
• 正文 [attach=id] 解析为对象存储 URL

URL 矩阵

Legacy 内容向（必须业务可达）

/、/index.php?action=…、/show-{id}[-{page}].shtml、/category-{cid}[-{page}].shtml、/archives…、/tagslist…、/index.php?action=tags&item=、/comments…、/search…、/links.shtml、/reg.shtml、/login.shtml、/rss.xml[?cid=]、/sitemap.xml、/attachment.php、/attachments/{path}、/post.php（登录/注册/评论/搜索）

新 canonical

• /tag/{name}（自旧 tags query 301）
• /llms.txt
• 可选 /posts/{slug}（不取代 show-id）

明确废弃（410，无业务）

• /tburl.php、/trackback.php
• 旧 /admin/*.php（非 Filament 面板）
• WAP 相关路径（若出现）

主题 / 插件 / Workerman / 导入

同前：主题回退、插件生命周期、AI 双队列、sablog:import 幂等与「跳过废弃表」报告；不删源数据。

验收标准

• 内容向 Legacy URL 可达；文章/分类 ID 与源一致（upsertWithId + fixture 回归）
• 无 Trackback 功能/表/设置；tb 入口 410
• 导入报告含「跳过 trackbacks/searchindex/sessions」计数
• 正文：新建默认 Markdown；导入默认可为 HTML；格式开关可切换；Markdown/HTML 渲染正确；--mode=markdown
• 前台评论闭环（含 AI 管道 stub）；仅 approved 展示
• Filament 管理内容与配置（含 content_format；无 trackback 菜单）
• 附件对象存储（生产 S3；开发 local）；双入口 302；主题可切换；插件可启停
• SEO/GEO 正常；Web 无同步 LLM；legacy MD5 可升级登录
• 导入幂等且不改源

开放问题

• 现代化：剔除 Trackback 等过时能力 — 已定
• 部署环境对象存储凭据；开发可用 MinIO / fake

变更记录

时间	原因	变更
2026-08-11 17:14	初稿	创建 SPEC
2026-08-11 17:20	qodercli A1–A8	URL/附件/映射等
2026-08-11 17:25	qodercli 映射缺口	补字段
2026-08-11 17:26	三轮无阻塞；用户确认	定稿
2026-08-11 17:35	用户：勿迁 trackback 等过时设计	增加现代化取舍；删除 Trackback 全链路；废弃入口 410；导入跳过垃圾表
2026-08-11 17:42	用户：HTML 旧文 / Markdown 未来	增加 content_format 双轨、站点/导入开关、可选 HTML→MD 转换
2026-08-11 17:50	用户：导入双份 + attach 与 MD 保留字	明确 DB 存引用、渲染期解析；`--mode=raw
2026-08-11 17:53	用户：自动配图/生成配图可后推	延期章节 + cover 字段/Job 空壳预留