修改readme

2026-03-19 16:50:25 +08:00 · 2026-03-19 16:50:25 +08:00 · 04eccc850d
parent ff2af385b9
commit 04eccc850d
1 changed files with 203 additions and 39 deletions
--- a/README.md
+++ b/README.md
@ -1,59 +1,223 @@
-<p align="center"><a href="https://laravel.com" target="_blank"><img src="https://raw.githubusercontent.com/laravel/art/master/logo-lockup/5%20SVG/2%20CMYK/1%20Full%20Color/laravel-logolockup-cmyk-red.svg" width="400" alt="Laravel Logo"></a></p>
+# Tstore

-<p align="center">
-<a href="https://github.com/laravel/framework/actions"><img src="https://github.com/laravel/framework/workflows/tests/badge.svg" alt="Build Status"></a>
-<a href="https://packagist.org/packages/laravel/framework"><img src="https://img.shields.io/packagist/dt/laravel/framework" alt="Total Downloads"></a>
-<a href="https://packagist.org/packages/laravel/framework"><img src="https://img.shields.io/packagist/v/laravel/framework" alt="Latest Stable Version"></a>
-<a href="https://packagist.org/packages/laravel/framework"><img src="https://img.shields.io/packagist/l/laravel/framework" alt="License"></a>
-</p>
+Tstore 是一个基于 Laravel 12 的 Typecho 插件/主题商店项目，包含展示前台、网页后台和 API 接口三部分。

-## About Laravel
+## 功能概览

-Laravel is a web application framework with expressive, elegant syntax. We believe development must be an enjoyable and creative experience to be truly fulfilling. Laravel takes the pain out of development by easing common tasks used in many web projects, such as:
+- 前台展示站：首页、插件列表、主题列表、详情页
+- 网页后台：账号密码登录、分类管理、扩展管理、版本管理、ZIP 发布
+- 仓库 API：扩展列表、详情、更新检查、下载、分类
+- 管理 API：包管理、分类管理、版本管理

- [Simple, fast routing engine](https://laravel.com/docs/routing).
- [Powerful dependency injection container](https://laravel.com/docs/container).
- Multiple back-ends for [session](https://laravel.com/docs/session) and [cache](https://laravel.com/docs/cache) storage.
- Expressive, intuitive [database ORM](https://laravel.com/docs/eloquent).
- Database agnostic [schema migrations](https://laravel.com/docs/migrations).
- [Robust background job processing](https://laravel.com/docs/queues).
- [Real-time event broadcasting](https://laravel.com/docs/broadcasting).
+## 技术栈

-Laravel is accessible, powerful, and provides tools required for large, robust applications.
+- PHP 8.2+
+- Laravel 12
+- Vite 7
+- Tailwind CSS 4

-## Learning Laravel
+## 主要入口

-Laravel has the most extensive and thorough [documentation](https://laravel.com/docs) and video tutorial library of all modern web application frameworks, making it a breeze to get started with the framework. You can also check out [Laravel Learn](https://laravel.com/learn), where you will be guided through building a modern Laravel application.
+- 前台首页：`/`
+- 后台登录：`/admin/login`
+- 仓库 API：`/api/v1/repo/*`
+- 管理 API：`/api/admin/*`
+- 健康检查：`/up`

-If you don't feel like reading, [Laracasts](https://laracasts.com) can help. Laracasts contains thousands of video tutorials on a range of topics including Laravel, modern PHP, unit testing, and JavaScript. Boost your skills by digging into our comprehensive video library.
+## 本地开发

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

-We would like to extend our thanks to the following sponsors for funding Laravel development. If you are interested in becoming a sponsor, please visit the [Laravel Partners program](https://partners.laravel.com).
+也可以直接使用项目内置脚本：

-### Premium Partners
+```bash
+composer run setup
+composer run dev
+```

- **[Vehikl](https://vehikl.com)**
- **[Tighten Co.](https://tighten.co)**
- **[Kirschbaum Development Group](https://kirschbaumdevelopment.com)**
- **[64 Robots](https://64robots.com)**
- **[Curotec](https://www.curotec.com/services/technologies/laravel)**
- **[DevSquad](https://devsquad.com/hire-laravel-developers)**
- **[Redberry](https://redberry.international/laravel-development)**
- **[Active Logic](https://activelogic.com)**
+## 生产部署

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

-Thank you for considering contributing to the Laravel framework! The contribution guide can be found in the [Laravel documentation](https://laravel.com/docs/contributions).
+### 1. 准备运行环境

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

-In order to ensure that the Laravel community is welcoming to all, please review and abide by the [Code of Conduct](https://laravel.com/docs/contributions#code-of-conduct).
+### 2. 拉取代码并安装依赖

-## Security Vulnerabilities
+```bash
+git clone <your-repo-url> /var/www/tstore
+cd /var/www/tstore

-If you discover a security vulnerability within Laravel, please send an e-mail to Taylor Otwell via [taylor@laravel.com](mailto:taylor@laravel.com). All security vulnerabilities will be promptly addressed.
+composer install --no-dev --optimize-autoloader
+npm ci
+npm run build
+```

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

-The Laravel framework is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).
+### 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`