laralog/docs/import.md

Sablog 数据导入指南

把 SaBlog-X 1.6 老站数据完整迁入 LaraLog。全部脚本化、可重复执行，保留原始 ID，老 URL 自动 301 兼容（不产生 SEO 404）。

前置准备

1. 老库可访问：MySQL 8（或可导出的老 MySQL 5.x，先在 MySQL 8 建好导入目标）
2. 老附件目录：sablog 的 attachments/（在 Web 服务器上，含编号子目录）
3. 已按 docs/install.md 完成安装（migrate --seed 后导入）

建议：先在测试环境用 --dry-run 风格（见下文幂等说明）完整跑一遍，确认数量后再上生产。

一键导入

php artisan sablog:import \
  --host=127.0.0.1 --port=3306 \
  --database=sablog --username=root --password=老库密码 \
  --prefix=sablog_ \
  --attachments-dir=/var/www/old/attachments \
  --sync-attachments \
  --convert-markdown

参数说明

参数	默认	说明
--driver	mysql	老库驱动（测试可用 sqlite）
--host / --port	127.0.0.1 / 3306	老库地址
--database	（必填）	老库名
--username / --password	root / 空	老库账号
--prefix	sablog_	老表前缀（老站可能自定义过）
--attachments-dir	—	老附件目录，配合 --sync-attachments 用
--sync-attachments	关	同步附件文件到新存储（本地中转或直接上 S3）
--convert-markdown	关	导入时把 HTML 正文转为 Markdown
--fresh	关	清空目标表后重新导入

数据映射

老表	新表	说明
users	users	ID 保留；老 MD5 密码进 legacy_md5，登录时自动升级为 bcrypt
articles	posts	articleid 保留为 id；[attach=xx] 按内容格式处理（见下）
categories	categories	cid 保留；导入后自动重算文章数
comments	comments	commentid 保留；visible 语义映射为状态
links	links	linkid 保留
attachments	medialibrary media	文件 + legacy_attachmentid 映射（老 [attach=xx] 按此解析）
settings	settings	键值映射为站点设置（可在后台「博客设置」继续改）
tags	spatie tags	老 aids 文本解析为独立标签 + 关联

不迁移：trackback/引用通告（垃圾来源，接口已关闭）、搜索缓存表、验证码（由 AI 审核 + 蜜罐 + 频控取代）。

附件短代码的处理

老内容	导入后
HTML 正文 [attach=12]	原样保留，渲染时按 legacy id 解析为附件链接/图片
Markdown 正文（--convert-markdown）	自动转成 {{attach:12}} 令牌（[] 是 Markdown 保留字符）

两种格式都能正常显示老附件，无需手工替换。

老 URL 兼容（301，无需 Nginx 配置）

• 伪静态：/show-12-1.html → 新文章页；/category-3-1.html → 新分类页；/archives-202008-1.html → 新归档
• 查询串：/?action=show&id=12、/?action=search&keyword=x、/?action=tags&id=1 …全部映射
• 稳定路径：/rss.xml、/sitemap.xml、/robots.txt 保持原样
• 老入口：attachment.php?id= → 301 到 S3/本地媒体地址；tburl.php/trackback.php → 410

附件上 S3

# 导入后再把老附件批量上传（Multipart、幂等、可断点续传）
php artisan attachments:sync-s3 --legacy-dir=/var/www/old/attachments

# 个别文件校验失败需要强制重传
php artisan attachments:sync-s3 --legacy-dir=... --force

未配置 S3 时附件留在本地 public 磁盘，网站可正常展示；配好 S3 后再执行同步即可无缝切换。

内容转换（可选）

php artisan content:convert --all          # 全部 HTML 文章转 Markdown
php artisan content:convert 12             # 单篇
php artisan content:convert --all --dry-run # 先预览

幂等与重跑

• 导入按原始 ID updateOrInsert：重复执行不会产生重复数据，只会覆盖更新
• 需要完全重来：--fresh 清空目标表后导入
• attachments:sync-s3 自带去重：已上传的文件跳过（除非 --force）

导入后检查清单

• 文章总数、评论总数与老站一致（后台仪表盘 / SELECT COUNT(*)）
• 抽查老 URL：/show-12-1.html 301 到新文章页
• 抽查带 [attach=xx] 的文章：附件正常显示
• 老账号用原密码登录成功（密码自动升级为 bcrypt）
• 分类文章数、文章评论数正确（导入脚本已自动重算）
• RSS/Sitemap 正常输出
• 主题切换后前台布局正常

常见问题

现象	处理
报「找不到老表」	检查 --prefix（老站表前缀可能不是 sablog_）与老库名
附件显示不出来	确认 --attachments-dir 路径正确；看 attachments:sync-s3 输出报告
老密码登录失败	老库密码若是自定义加密（非 MD5），需要按 User::verifyPassword 扩展
中文乱码	老库导出时用 utf8mb4；--driver=sqlite 只用于测试