宝塔面板部署

按 webman 宝塔安装 的「PHP 项目 → 异步项目」部署。下面截图来自该手册，步骤与之相同。

本项目按下面三处填写，手册示例里的空项目和 8787 端口对不上：

• 项目目录用仓库里的 server/（含 start.php）
• HTTP 监听 8000，管理员 WebSocket 监听 8001。伪静态上游写这两个端口
• 安装地址是 https://你的域名/install/

下文以 /www/wwwroot/ydadmin/server 为例，换成你的实际目录。

0. 环境

在宝塔软件商店安装：

• PHP 8.4
• MySQL 8
• Redis
• Composer（PHP 版本选 8.4）

PHP 8.4 里安装扩展 redis。pcntl、posix 随 PHP 自带，但宝塔默认把它们关进禁用函数。打开「软件商店 → PHP-8.4 → 设置 → 禁用函数」，删掉所有 pcntl_*，以及 putenv、exec、proc_open、shell_exec。

1. 安装依赖

在宝塔左侧打开终端，克隆仓库后进入 server 目录，复制环境文件并安装依赖：

cd /www/wwwroot
git clone https://github.com/yuandianxitong/ydadmin.git
cd /www/wwwroot/ydadmin/server
cp .env.example .env
composer install --no-dev

生产环境把 .env 里的 APP_DEBUG 设为 false。数据库和 Redis 可以先留空，安装向导会写回 .env。TRUSTED_PROXIES 填 127.0.0.1，这样 nginx 反代过来的 X-Forwarded-* 才会生效。

2. 添加异步项目

「网站 → PHP 项目 → 添加站点」，项目类型选「异步项目」。

项	填写
项目目录	/www/wwwroot/ydadmin/server（含 start.php 的目录）
PHP 版本	PHP-84
数据库	不创建。库在安装向导里填
运行用户	www
启动命令	php /www/wwwroot/ydadmin/server/start.php start

启动命令使用 start.php 的绝对路径。末尾不要加 -d。宝塔自己守护进程，加上 -d 后父进程立刻退出，面板会显示启动失败、pid 为 0。

3. 打开站点设置

添加完成后，在 PHP 项目列表里点该站点的「设置」。

4. 运行目录

在「服务管理」里把运行目录设为 /public，保存。

运行目录是 nginx 的网站根。设成 /public 后，外网只能访问静态资源；设成 / 时，.env 等文件会暴露在网站根下。

5. 伪静态

打开「配置文件 → 伪静态配置文件」，贴上下面的配置。在手册原配置上加了 /ws，并把 8787 改成了 8000。

# 管理员 WebSocket
location /ws {
    proxy_pass http://127.0.0.1:8001;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_read_timeout 3600s;
}

# 将请求转发到 webman。public 下真实存在的文件由 nginx 直接返回
location ^~ / {
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    if (!-f $request_filename) {
        proxy_pass http://127.0.0.1:8000;
    }
}

# 拒绝访问所有以 .php 结尾的文件
location ~ \.php$ {
    return 404;
}

# 允许访问 .well-known 目录
location ~ ^/\.well-known/ {
    allow all;
}

# 拒绝访问所有以 . 开头的文件或目录
location ~ /\. {
    return 404;
}

再到「nginx 配置文件」的 server 块里加上上传限制：

client_max_body_size 50m;

保存后重载 nginx。80 / 443 由宝塔转发，不必在防火墙放行 8000 和 8001。

6. runtime 可写

面板用 www 启动。若目录是 root 上传的，或之前用 root 启动过，www 写不了 pid 和日志。在终端执行：

chown -R www:www /www/wwwroot/ydadmin/server/runtime
chmod -R 777 /www/wwwroot/ydadmin/server/runtime

宝塔有时会把进程实际跑成 daemon 而不是 www。上面的 777 就是为了这种偏差仍然能写入。

7. 启动

回到「服务管理」，点「启动」或「重启」。状态变为「开启」，pid 不是 0，即进程已拉起。这一条命令会同时拉起 HTTP、定时任务、队列和 WebSocket。

8. 安装系统

浏览器打开 https://你的域名/install/，按向导填数据库、Redis 和管理员密码。超级管理员用户名默认 admin。

装完必须再点一次面板上的「重启」（或在 server 目录执行 php start.php restart）。只刷新页面不会重新读取 .env 和安装锁。然后访问 https://你的域名/admin/。

故障排查

启动失败，日志里却已经启动

打开左侧「项目日志」。若日志里 Workerman 已经打印启动成功，面板仍提示启动失败，再看 systemd：

journalctl -u 你的域名.service -n 30 --no-pager

出现 start operation timed out 时，是宝塔生成的服务类型在等进程退出。php start.php start 会停在前台，大约 90 秒后被判定超时并杀掉。加一段覆盖，把类型改成前台进程：

systemctl stop 你的域名
mkdir -p /etc/systemd/system/你的域名.service.d
cat > /etc/systemd/system/你的域名.service.d/override.conf << 'EOF'
[Service]
Type=simple
PIDFile=
EOF
systemctl daemon-reload
systemctl reset-failed 你的域名
systemctl start 你的域名
systemctl status 你的域名 --no-pager

Active: active (running) 即为成功。这段覆盖放在 service.d 里，之后在面板点「保存」不会把它清掉。

站点 502

webman 没在监听。在服务器上执行：

curl -sI http://127.0.0.1:8000/install/
ss -lptn | grep -E ':8000|:8001'

本机没有 HTTP/1.1 200 时，回到「项目日志」看启动报错。常见原因：

• 禁用函数仍包含 pcntl_fork 或 putenv
• runtime 不可写
• 8000 或 8001 已被占用（Address already in use）。换端口时改 server/.env 的 SERVER_LISTEN、WS_LISTEN，伪静态里的上游端口一起改，然后在面板重启

打开域名 /install 没有安装页

请求停在 nginx，没有转到 8000。确认伪静态已保存、上游是 127.0.0.1:8000，并且运行目录是 /public。用上一节的 curl 区分：本机 200、域名不是，就是伪静态或 nginx 没重载。