319 lines
7.5 KiB
Markdown
319 lines
7.5 KiB
Markdown
# 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
|
||
```
|
||
|
||
## Docker
|
||
|
||
仓库已提供通用容器化文件：
|
||
|
||
- `Dockerfile`
|
||
- `.dockerignore`
|
||
- `docker/apache/000-default.conf`
|
||
- `docker/entrypoint.sh`
|
||
- `docker/php/opcache.ini`
|
||
- `docker-compose.example.yml`
|
||
|
||
### 1. 构建镜像
|
||
|
||
```bash
|
||
docker build -t tstore:latest .
|
||
```
|
||
|
||
这个镜像是多阶段构建，包含：
|
||
|
||
- Composer 依赖安装
|
||
- Vite 前端资源构建
|
||
- Apache + PHP 8.2 运行时
|
||
|
||
容器内网站根目录已经指向 `public/`，不需要再额外改 Web 根目录。
|
||
|
||
### 2. 单容器运行
|
||
|
||
更适合已经有外部 MySQL 的场景。
|
||
|
||
```bash
|
||
docker run -d \
|
||
--name tstore \
|
||
-p 8080:80 \
|
||
--env-file .env \
|
||
-e APP_ENV=production \
|
||
-e APP_DEBUG=false \
|
||
-e APP_URL=http://localhost:8080 \
|
||
-e LOG_CHANNEL=stderr \
|
||
-e DB_CONNECTION=mysql \
|
||
-e DB_HOST=your-db-host \
|
||
-e DB_PORT=3306 \
|
||
-e DB_DATABASE=tstore \
|
||
-e DB_USERNAME=tstore \
|
||
-e DB_PASSWORD=your-password \
|
||
-e SESSION_DRIVER=file \
|
||
-e CACHE_STORE=file \
|
||
-e QUEUE_CONNECTION=sync \
|
||
-e RUN_MIGRATIONS=1 \
|
||
-e RUN_OPTIMIZE=1 \
|
||
tstore:latest
|
||
```
|
||
|
||
如果你希望容器启动时自动创建后台管理员账号，可以再加：
|
||
|
||
```bash
|
||
-e RUN_ADMIN_SEEDER=1
|
||
```
|
||
|
||
说明：
|
||
|
||
- `RUN_MIGRATIONS=1` 会在容器启动时执行 `php artisan migrate --force`
|
||
- `RUN_ADMIN_SEEDER=1` 会执行 `AdminUserSeeder`
|
||
- `RUN_OPTIMIZE=1` 会执行 `php artisan optimize`
|
||
|
||
### 3. 使用 Docker Compose
|
||
|
||
仓库提供了一个通用示例文件：
|
||
|
||
```bash
|
||
cp docker-compose.example.yml docker-compose.yml
|
||
docker compose up -d --build
|
||
```
|
||
|
||
默认暴露端口：
|
||
|
||
- 应用：`8080`
|
||
- MySQL：不对宿主机暴露，仅供容器内部访问
|
||
|
||
首次启动前，建议先修改：
|
||
|
||
- `docker-compose.yml` 中的数据库密码
|
||
- `.env` 中的 `APP_URL`
|
||
- `.env` 中的 `SESSION_DRIVER`、`CACHE_STORE`、`QUEUE_CONNECTION`
|
||
- `.env` 中的 `STORE_ADMIN_TOKEN`
|
||
- `.env` 中的 `STORE_PLUGIN_ACCESS_TOKEN`
|
||
- `.env` 中的 `ADMIN_EMAIL`
|
||
- `.env` 中的 `ADMIN_PASSWORD`
|
||
|
||
### 4. 容器化运行时建议
|
||
|
||
- 生产环境优先使用 MySQL，不建议继续使用 SQLite
|
||
- 如果要持久化上传的 ZIP 包和日志，保留 `storage` 卷挂载
|
||
- 不要把真实 `.env` 打进镜像，运行时通过 `--env-file` 或 Compose 注入
|
||
- 如果上线到生产，建议把 `APP_URL` 改成正式域名，并在网关层处理 HTTPS
|
||
|
||
## 生产部署
|
||
|
||
以下步骤以 `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`
|