# Tstore

Tstore 是一个基于 Laravel 12 的 Typecho 插件/主题商店项目，包含展示前台、网页后台和 API 接口三部分。

## 功能概览

- 前台展示站：首页、插件列表、主题列表、详情页
- 网页后台：账号密码登录、分类管理、扩展管理、版本管理、ZIP 发布
- 仓库 API：扩展列表、详情、更新检查、下载、分类
- 管理 API：包管理、分类管理、版本管理

## 技术栈

- PHP 8.2+
- Laravel 12
- Vite 7
- Tailwind CSS 4

## 主要入口

- 前台首页：`/`
- 后台登录：`/admin/login`
- 仓库 API：`/api/v1/repo/*`
- 管理 API：`/api/admin/*`
- 健康检查：`/up`

## 本地开发

```bash
composer install
cp .env.example .env
php artisan key:generate
php artisan migrate --force
npm install
npm run dev
php artisan serve
```

也可以直接使用项目内置脚本：

```bash
composer run setup
composer run dev
```

## 生产部署

以下步骤以 `Linux + Nginx + PHP-FPM` 为例。生产环境不要运行 `php artisan serve` 和 `npm run dev`。

### 1. 准备运行环境

- 安装 PHP 8.2 及常用扩展：`mbstring`、`openssl`、`pdo`、`pdo_mysql` 或 `pdo_sqlite`、`fileinfo`、`zip`
- 安装 Composer 2
- 安装 Node.js 20+ 和 npm
- 准备 Web 服务器，例如 Nginx
- 准备数据库，生产建议使用 MySQL 或 MariaDB，不建议继续使用 SQLite

### 2. 拉取代码并安装依赖

```bash
git clone <your-repo-url> /var/www/tstore
cd /var/www/tstore

composer install --no-dev --optimize-autoloader
npm ci
npm run build
```

如果前端资源在 CI 中已经构建好，也可以直接发布 `public/build`，服务器上就不必再执行 `npm ci` 和 `npm run build`。

### 3. 配置环境变量

先创建生产环境配置文件：

```bash
cp .env.example .env
```

至少确认并修改以下配置：

```dotenv
APP_NAME=Tstore
APP_ENV=production
APP_DEBUG=false
APP_URL=https://your-domain.com

LOG_CHANNEL=stack
LOG_STACK=daily
LOG_LEVEL=info

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=tstore
DB_USERNAME=tstore
DB_PASSWORD=your-password

SESSION_DRIVER=file
CACHE_STORE=file
QUEUE_CONNECTION=sync

STORE_ADMIN_TOKEN=replace-with-a-long-random-token
STORE_PLUGIN_ACCESS_TOKEN=replace-with-a-long-random-token

ADMIN_NAME=Tstore Admin
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=change-this-password
```

说明：

- `STORE_ADMIN_TOKEN` 用于 `/api/admin/*` 管理接口鉴权
- `STORE_PLUGIN_ACCESS_TOKEN` 用于下载接口鉴权
- 网页后台 `/admin/login` 使用 `users` 表中的账号密码登录
- 如果生产环境使用 Redis，可以把 `SESSION_DRIVER`、`CACHE_STORE`、`QUEUE_CONNECTION` 改为 Redis 相关配置

### 4. 初始化应用

```bash
php artisan key:generate
php artisan migrate --force
php artisan db:seed --class='Database\Seeders\AdminUserSeeder' --force
php artisan optimize
```

说明：

- 首次部署需要执行 `key:generate`
- 初始化管理员账号时，只建议运行 `AdminUserSeeder`
- 不要在生产环境直接执行 `php artisan db:seed`，因为当前 `DatabaseSeeder` 会同时导入演示数据

### 5. 设置目录权限

确保以下目录对 Web 服务用户可写：

- `storage/`
- `bootstrap/cache/`

如果你把上传的 ZIP 包存放在本机磁盘，还需要关注：

- `storage/app/packages/`

这个目录建议纳入备份策略。

### 6. 配置 Web 根目录

Nginx 或 Apache 的站点根目录必须指向项目的 `public/` 目录，而不是仓库根目录。

例如：

```nginx
server {
    listen 80;
    server_name your-domain.com;
    root /var/www/tstore/public;
    index index.php index.html;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}
```

### 7. 部署后验证

部署完成后，至少检查以下内容：

- 访问 `/up`，确认健康检查正常
- 访问 `/admin/login`，确认后台登录页正常打开
- 检查 `public/build/manifest.json` 是否存在
- 调用 `/api/v1/repo/index`，确认公开 API 正常返回
- 登录后台，确认可进入管理首页

### 8. 后续发布更新

应用更新时，建议按下面顺序执行：

```bash
cd /var/www/tstore
git pull

composer install --no-dev --optimize-autoloader
npm ci
npm run build

php artisan migrate --force
php artisan optimize:clear
php artisan optimize
```

### 9. 可选：队列进程

当前项目即使使用 `QUEUE_CONNECTION=sync` 也可以正常工作。如果你后续把下载日志、统计或发布流程改成异步任务，再配置常驻队列进程，例如：

```bash
php artisan queue:work --tries=3 --timeout=90
```

建议用 Supervisor 或 systemd 托管。

## 生产环境建议

- `APP_DEBUG` 必须为 `false`
- 使用 HTTPS，并正确设置 `APP_URL`
- 管理 API 令牌和下载令牌使用高强度随机值
- 日志建议使用 `daily`
- 数据库、`storage/app/packages` 和 `.env` 要纳入备份

## 备注

- 生产环境不需要运行 Vite 开发服务器
- 生产环境不建议使用 `php artisan serve`
- 如果前端资源已由 CI 构建，可以只发布编译后的 `public/build`