ak
43dc8f9856
- docs/install.md：全新安装指南（环境要求/.env/验收清单/常见问题） - docs/import.md：Sablog 导入全解（命令参数表/数据映射/附件短代码/301 兼容/S3 同步/幂等重跑/检查清单） - docs/deploy.md：补生产迁移顺序、上线前检查清单、调度器实际内容 - Workerman 进程文件（pid/status/log）统一写入 storage/framework 与 storage/logs，不再出现在项目根目录；.gitignore 排除并清理根目录残留 - README 文档导航补 install/import
114 lines
5.0 KiB
Markdown
114 lines
5.0 KiB
Markdown
# 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` 风格（见下文幂等说明）完整跑一遍，确认数量后再上生产。
|
||
|
||
## 一键导入
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
# 导入后再把老附件批量上传（Multipart、幂等、可断点续传）
|
||
php artisan attachments:sync-s3 --legacy-dir=/var/www/old/attachments
|
||
|
||
# 个别文件校验失败需要强制重传
|
||
php artisan attachments:sync-s3 --legacy-dir=... --force
|
||
```
|
||
|
||
> 未配置 S3 时附件留在本地 public 磁盘，网站可正常展示；配好 S3 后再执行同步即可无缝切换。
|
||
|
||
## 内容转换（可选）
|
||
|
||
```bash
|
||
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` 只用于测试 |
|