# 安装指南

从零安装 LaraLog。已有 SaBlog-X 老数据的先看本页，数据迁移见 `docs/import.md`，上线见 `docs/deploy.md`。

## 环境要求

| 组件 | 要求 |
|------|------|
| PHP | **8.2+**（需 pcntl 扩展用于 Workerman；GD/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              # 开发期：监听代码变化自动重启 workerman（fswatch 或 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_*` 键与桶权限 |
| 插件停用后功能消失 | 属预期：付费列/外链中转等由插件注入，后台「插件管理」重新启用即可 |