宝塔面板部署

本文档详细介绍如何使用宝塔面板部署元点Admin 到生产环境，涵盖从安装到上线的完整流程。

1. 环境准备

安装宝塔面板

TIP

如果你已安装宝塔面板，可跳到"安装软件"步骤。

# CentOS
yum install -y wget && wget -O install.sh https://download.bt.cn/install/install_6.0.sh && sh install.sh ed8484bec

# Ubuntu / Debian
wget -O install.sh https://download.bt.cn/install/install-ubuntu_6.0.sh && sudo bash install.sh ed8484bec

安装完成后，浏览器访问面板地址（终端会显示），使用初始账号密码登录。

安装软件

在宝塔面板「软件商店」中安装以下软件：

软件	推荐版本	说明
Nginx	1.24+	Web 服务器
PHP	8.2	后端运行环境
MySQL	8.0	数据库（5.7 也可用）
Redis	7.0	缓存和队列

WARNING

PHP 版本必须 >= 8.0，低于此版本无法运行 ThinkPHP 8。

安装 PHP 扩展

在「软件商店 → PHP 8.2 → 设置 → 安装扩展」中安装：

• fileinfo — 文件上传类型检测（必须）
• redis — Redis 缓存驱动（必须）
• exif — 图片 EXIF 信息读取

解禁 PHP 函数

在「PHP 8.2 → 设置 → 禁用函数」中，移除以下函数：

• putenv — Composer 需要
• proc_open — Composer 需要
• proc_get_status — Composer 需要
• pcntl_signal — 队列进程需要
• pcntl_alarm — 队列进程需要

DANGER

不解禁这些函数会导致 Composer 安装失败和队列进程无法启动。

2. 创建站点

添加网站

在「网站 → 添加站点」中填写：

配置项	值
域名	你的域名（如 admin.example.com）
根目录	/www/wwwroot/ydadmin/server/public
PHP 版本	PHP-82
数据库	MySQL（此处可以直接创建）

关键

根目录必须指向 server/public，不是 server 也不是项目根目录。

配置伪静态

在「网站 → 你的站点 → 设置 → 伪静态」中，选择 thinkphp 模板，或手动填入：

location / {
    if (!-e $request_filename) {
        rewrite ^(.*)$ /index.php/$1 last;
    }
}

3. 代码部署

方式一：Git 拉取（推荐）

cd /www/wwwroot
git clone https://github.com/yuandianxitong/ydadmin.git

后续更新只需 git pull。

方式二：文件管理器上传

1. 本地将项目打包为 zip
2. 在宝塔「文件管理器」中上传到 /www/wwwroot/
3. 解压

安装后端依赖

cd /www/wwwroot/ydadmin/server
composer install --no-dev --optimize-autoloader

TIP

--no-dev 排除开发依赖，--optimize-autoloader 优化自动加载，适合生产环境。

目录权限

chmod -R 755 /www/wwwroot/ydadmin/server/runtime
chmod -R 755 /www/wwwroot/ydadmin/server/public/storage
chown -R www:www /www/wwwroot/ydadmin/server/runtime
chown -R www:www /www/wwwroot/ydadmin/server/public/storage

4. 数据库配置

创建数据库

如果在添加站点时没有创建数据库，可以在「数据库 → 添加数据库」中创建：

配置项	值
数据库名	yd_admin
字符集	utf8mb4
排序规则	utf8mb4_unicode_ci

运行安装向导

浏览器访问 http://your-domain.com/install/，按向导完成安装。安装向导会自动导入数据库结构和初始数据。

手动导入（可选）

如果不使用安装向导：

cd /www/wwwroot/ydadmin/server
mysql -u yd_admin -p yd_admin < public/install/data/schema.sql
mysql -u yd_admin -p yd_admin < public/install/data/init.sql

然后手动编辑 .env 文件配置数据库连接。

5. 前端构建与部署

管理后台前端代码已预编译在 server/public/admin/ 目录。如果没有二次开发需求，无需额外构建。

如果有前端修改，在本地构建后上传：

# 本地机器执行
cd admin
pnpm install
pnpm build
# 构建产物在 server/public/admin/ 目录

Nginx 完整配置示例

以下是前后端分离的完整 Nginx 配置，在「网站 → 设置 → 配置文件」中编辑：

server {
    listen 80;
    server_name your-domain.com;
    root /www/wwwroot/ydadmin/server/public;
    index index.php index.html;

    # 管理后台前端（SPA）
    location /admin {
        try_files $uri $uri/ /admin/index.html;
    }

    # 静态资源缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
        expires 30d;
        add_header Cache-Control "public, no-transform";
    }

    # 后端 API（ThinkPHP 伪静态）
    location / {
        if (!-e $request_filename) {
            rewrite ^(.*)$ /index.php/$1 last;
        }
    }

    # PHP-FPM
    location ~ \.php(.*)$ {
        fastcgi_pass unix:/tmp/php-cgi-82.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param PATH_INFO $1;
        include fastcgi_params;
    }

    # 禁止访问隐藏文件
    location ~ /\. {
        deny all;
    }

    access_log /www/wwwlogs/ydadmin.log;
    error_log /www/wwwlogs/ydadmin.error.log;
}

6. SSL 证书配置

申请免费证书

在「网站 → 设置 → SSL → Let's Encrypt」中：

1. 勾选域名
2. 选择"文件验证"
3. 点击"申请"

强制 HTTPS

申请成功后，开启"强制 HTTPS"选项。

更新 .env

确保 .env 中没有硬编码 HTTP 地址，系统会自动识别当前协议。

7. Redis 配置

验证 Redis 服务

redis-cli ping
# 应返回 PONG

配置 .env

[CACHE]
DRIVER = redis

[REDIS]
HOST = 127.0.0.1
PORT = 6379
PASSWORD =

[QUEUE]
CONNECTOR = redis

修改后清除缓存：

cd /www/wwwroot/ydadmin/server
php think clear

8. 队列进程守护（Supervisor）

操作日志和消息通知默认通过队列异步处理，需要 Supervisor 保持队列进程常驻。

安装 Supervisor

在宝塔「软件商店」中搜索并安装「Supervisor管理器」。

添加守护进程

在「Supervisor管理器 → 添加守护进程」中配置：

配置项	值
名称	ydadmin-queue
启动命令	php think queue:work --daemon --tries=3
运行目录	/www/wwwroot/ydadmin/server
进程数量	1（小型项目足够，大型项目可设 2-4）
启动用户	www

验证

ps aux | grep queue:work
# 应能看到 php think queue:work 进程

TIP

如果队列不生效，检查 .env 中 QUEUE.CONNECTOR 是否设为 redis，以及 Redis 服务是否正常。

9. 定时任务（Cron）

在宝塔「计划任务 → 添加计划任务」中配置：

任务	类型	执行周期	命令
日志归档	Shell脚本	每天凌晨 3:00	cd /www/wwwroot/ydadmin/server && php think log:archive

脚本内容：

#!/bin/bash
cd /www/wwwroot/ydadmin/server
php think log:archive >> /www/wwwlogs/ydadmin-cron.log 2>&1

10. 生产环境优化

关闭调试模式

# .env
APP_DEBUG = false
APP_TRACE = false

DANGER

生产环境务必关闭调试模式，否则会暴露敏感信息（SQL 语句、文件路径等）。

PHP OPcache

在「PHP → 设置 → 配置修改」中确保 OPcache 已启用：

opcache.enable=1
opcache.memory_consumption=128
opcache.max_accelerated_files=10000
opcache.validate_timestamps=0  ; 生产环境设为0，代码更新后需重启PHP

WARNING

validate_timestamps=0 时，更新代码后需重启 PHP 服务才能生效。

Nginx Gzip 压缩

在「网站 → 设置 → 配置文件」的 server 块中添加：

gzip on;
gzip_min_length 1k;
gzip_comp_level 6;
gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
gzip_vary on;

MySQL 调优建议

在宝塔「数据库 → MySQL设置」中：

innodb_buffer_pool_size = 256M   # 服务器内存的 50-70%
max_connections = 200
query_cache_type = 0             # MySQL 8.0 已移除，忽略

11. 常见问题

页面 404

原因： 伪静态未配置或配置错误。

解决： 检查「网站 → 设置 → 伪静态」是否选择了 thinkphp 模板。

接口 500 错误

排查步骤：

1. 检查 server/runtime/log/ 下的日志文件
2. 检查目录权限（runtime/、public/storage/）
3. 检查 PHP 扩展是否安装完整

Composer 安装失败

常见原因： PHP 函数被禁用。

解决： 在 PHP 设置中解禁 putenv、proc_open、proc_get_status。

接口跨域

如果前端单独部署到其他域名，需要在 Nginx 中添加 CORS 头：

location /adminapi {
    add_header Access-Control-Allow-Origin *;
    add_header Access-Control-Allow-Methods 'GET, POST, PUT, DELETE, OPTIONS';
    add_header Access-Control-Allow-Headers 'Authorization, Content-Type, X-Requested-With';

    if ($request_method = 'OPTIONS') {
        return 204;
    }
}

文件上传失败

检查项：

1. server/public/storage/ 目录权限
2. PHP 上传限制：upload_max_filesize、post_max_size（在 PHP 设置中调整）
3. Nginx 上传限制：client_max_body_size（在 Nginx 配置中调整）

更多问题请查看 常见问题排查。