# 安装（本地开发）

把 LaraBlog 跑起来：前台、Filament 后台、演示数据。从 sablog 迁站请先看 [import.md](./import.md)，**不要先灌演示数据**。上线见 [deploy.md](./deploy.md)。

## 环境

| 项 | 要求 |
|---|---|
| PHP | **8.2+**（`composer.json`） |
| 扩展 | `mbstring`、`openssl`、`pdo`、`tokenizer`、`xml`、`ctype`、`json`、`fileinfo`、`gd`（封面/图片）、`zip` |
| Composer | 2.x |
| 数据库 | 开发可用 SQLite；也可用 MySQL / MariaDB |
| 可选 | Redis（队列/缓存）；Node.js 仅在改前端资源时需要 |
| 可选 | `pcntl` + `posix`（本机跑 `workerman:ai`；没有就用 `queue:ai`） |

macOS 可用 Laravel Herd / Valet，指向仓库的 `public/`。也可用 `php artisan serve`。

## 1. 代码与依赖

```bash
cd /path/to/larablog
composer install
cp .env.example .env
php artisan key:generate
```

## 2. 配置 `.env`

最少改这些：

```env
APP_NAME=LaraBlog
APP_ENV=local
APP_DEBUG=true
APP_URL=http://larablog.test          # 必须和浏览器访问的 origin 一致
APP_LOCALE=zh_CN

# 开发默认 SQLite（文件需存在）
DB_CONNECTION=sqlite
# DB_DATABASE=/绝对路径/database/database.sqlite

# 开发附件落本地，不必配 S3
ATTACHMENTS_DRIVER=local

QUEUE_CONNECTION=database
CACHE_STORE=database
SESSION_DRIVER=database

# 本机没有真实 LLM 时用 stub，避免后台点「AI 润色」去打外网
AI_PROVIDER=stub
```

SQLite 文件：

```bash
mkdir -p database
touch database/database.sqlite
```

改用 MySQL 时：

```env
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=larablog
DB_USERNAME=root
DB_PASSWORD=
```

## 3. 初始化

```bash
php artisan migrate
php artisan db:seed
php artisan plugins:sync
php artisan migrate            # 插件表（支付/会员等）随 discover 加载，再跑一遍即可
php artisan themes:publish
```

`db:seed` 会：

- 写入 AI 设置（来自 `.env` 的 `AI_*`）
- 启用 `larablog/ai-comment-moderation`，并尝试启用 `payment` / `membership`
- 创建演示分类、文章、友情链接
- 创建后台账号

## 4. 启动

**Herd / nginx：** 站点根目录设为 `public/`，打开 `APP_URL`。

**内置服务器：**

```bash
php artisan serve
```

本地要排空队列（含 AI）可以另开终端：

```bash
php artisan queue:work --tries=3
# 或只处理 AI 队列（不会启动 Workerman）：
php artisan queue:ai
```

改 Filament/Vite 资源时才需要 `npm install && npm run dev`。主题 CSS 走 `php artisan themes:publish` 拷到 `public/themes/`。

## 5. 入口与账号

| 入口 | 地址 |
|---|---|
| 前台 | `/`、`/show-1.shtml`、`/login.shtml` |
| 后台 | `/admin` |
| API | `/api/v1/meta`、`/api/v1/articles` |
| OpenAPI | `/docs/api/openapi.yaml` |

演示管理员（`DemoBlogSeeder`）：

- 邮箱：`admin@larablog.test`
- 密码：`password`

登录后请立刻改密码。不要把这组账号用在公网。

## 6. 插件（可选）

```bash
php artisan plugins:sync
# 后台 → 插件 → 启用；或：
php artisan plugins:sync --enable=larablog/payment,larablog/membership
php artisan migrate
```

依赖顺序：先 `larablog/payment`，再 `larablog/paid-content` / `larablog/membership`。说明见后台卡片「使用说明」，以及 `docs/plugins.md`。

## 7. 自检

```bash
php artisan test
php artisan route:list --path=shtml
```

浏览器打开首页、一篇 `.shtml` 文章、`/admin`。本地附件地址形如 `/attachments-local/...`（由 Laravel 路由提供，不必 `storage:link`）。

## 常见问题

**500 / 空白页**  
`storage/`、`bootstrap/cache/` 对 PHP 进程可写；`APP_KEY` 已生成；`APP_DEBUG=true` 看 `storage/logs/laravel.log`。

**后台样式丢失**  
执行 `php artisan filament:upgrade` 与 `php artisan themes:publish`。

**点了 AI 润色没反应**  
`AI_PROVIDER=stub` 时也要有队列消费者；`QUEUE_CONNECTION=sync` 会在请求内执行（仅调试）。生产见 [deploy.md](./deploy.md)。

**准备导入旧站**  
不要用这份「演示种子」当生产数据。空库 `migrate` 后直接走 [import.md](./import.md)。