docs: 安装/导入文档 + 部署文档刷新 + workerman 进程文件收归 storage
CI / test (push) Failing after 7s
CI / deploy (push) Skipped

- 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
This commit is contained in:
ak
2026-08-13 05:00:22 +08:00
parent 6f13d13d5a
commit 43dc8f9856
6 changed files with 247 additions and 7 deletions
+94
View File
@@ -0,0 +1,94 @@
# 安装指南
从零安装 LaraLog。已有 SaBlog-X 老数据的先看本页,数据迁移见 `docs/import.md`,上线见 `docs/deploy.md`
## 环境要求
| 组件 | 要求 |
|------|------|
| PHP | **8.2+**(需 pcntl 扩展用于 WorkermanGD/Imagick 用于缩略图) |
| MySQL | **8.x** |
| Composer | 2.x |
| 可选 | Node.js(前台资源构建)、S3 兼容存储(R2/COS/OSS/MinIO)、OpenAI 兼容 LLM |
## 1. 获取代码与依赖
```bash
git clone <repo> laralog
cd laralog
composer install --no-dev # 开发环境不加 --no-dev
cp .env.example .env
php artisan key:generate
```
`.env.example` 已包含全部配置键,关键项:
```dotenv
APP_URL=http://laralog.test # 生产改正式域名(影响生成的全部链接)
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_DATABASE=laralog
DB_USERNAME=root
DB_PASSWORD=
# 以下为可选能力(不配也能跑,见注释):
# S3_* 附件存储(不配置回退本地 public)
# LLM_* AI 评论审核/润色
# MARKET_* 插件/主题远程市场
```
## 2. 建库与初始化
```bash
# 先在 MySQL 建库
mysql -uroot -p -e "CREATE DATABASE laralog CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci"
# 迁移 + 种子(创建管理员)
php artisan migrate --seed
```
**后台登录**`http://{APP_URL}/admin`,默认账号 `admin@laralog.test` / `password`**上线后第一时间改密码**)。
> 内置插件(SEO/AI/支付/会员/外链中转)随迁移自动建表并默认启用(config/plugins.php),后台「插件管理」可启停。
## 3. 开发环境运行
### Herd / Valet(推荐,macOS
```bash
# Herd:站点指向本目录即可,直接访问 http://laralog.test
```
### 内置服务器
```bash
php artisan serve # http://127.0.0.1:8000
```
### 队列消费者(AI 审核/润色才需要)
```bash
php artisan dev:watch # 开发期:监听代码变化自动重启 workermanfswatch 或 PHP 轮询兜底)
# 或简单模式
php artisan queue:work --queue=default,ai
```
## 4. 验收清单
- [ ] 前台首页/文章/分类/归档/标签/搜索/友链/登录注册正常
- [ ] 后台 `/admin` 登录成功,文章/评论/设置/主题/插件页面可访问
- [ ] 主题切换正常(后台「主题管理」,内置 sablog/modern/demo 三套)
- [ ] 发一条评论:评论区显示(若有 AI 配置,进审核队列)
- [ ] 支付:后台「支付设置」默认沙箱模式,会员套餐可走模拟支付闭环
- [ ] 文章写 `[hello 世界]` 变问候语(demo 插件启用后,`/hello-world` 可访问)
## 5. 常见问题
| 现象 | 处理 |
|------|------|
| 页面 500 / 空白 | `storage/``bootstrap/cache/` 目录需可写;`php artisan config:clear` |
| 中文乱码 | 数据库/连接字符集 utf8mb4 |
| 后台样式错乱 | `php artisan filament:assets`(重新发布后台资源) |
| 文章编辑框太小 | 已内置加大样式;仍不够可调整 `app/Providers/AppServiceProvider.php``.fi-fo-markdown-editor` 的 min-height |
| 附件上传失败 | 未配 S3 时走本地 public 磁盘;配 S3 后确认 `S3_*` 键与桶权限 |
| 插件停用后功能消失 | 属预期:付费列/外链中转等由插件注入,后台「插件管理」重新启用即可 |