7.5 KiB

Raw Permalink Blame History

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

本地开发

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

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

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. 构建镜像

docker build -t tstore:latest .

这个镜像是多阶段构建，包含：

Composer 依赖安装
Vite 前端资源构建
Apache + PHP 8.2 运行时

容器内网站根目录已经指向 public/，不需要再额外改 Web 根目录。

2. 单容器运行

更适合已经有外部 MySQL 的场景。

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

如果你希望容器启动时自动创建后台管理员账号，可以再加：

-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

仓库提供了一个通用示例文件：

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. 拉取代码并安装依赖

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. 配置环境变量

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

cp .env.example .env

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

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. 初始化应用

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/ 目录，而不是仓库根目录。

例如：

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. 后续发布更新

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

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 也可以正常工作。如果你后续把下载日志、统计或发布流程改成异步任务，再配置常驻队列进程，例如：

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

7.5 KiB Raw Permalink Blame History Unescape Escape