跳至主要内容

部署后端基座

2026/10/26大约 9 分钟

部署后端基座（am-serve）

后端基座 am-serve 有三种部署方式，任选一种往下走即可：

  • 方式一 · 发行包一键部署（推荐） —— 基座程序固定，依赖与前端产物都已内置，下载、解压、启动三步即可，适合生产上线。
  • 方式二 · 源码部署 —— 拉取 git 源码，自行安装依赖、构建前端、开发调试，适合开发者与二次开发。
  • 方式三 · 宝塔面板部署 —— 用面板建站、配反代并守护进程，运维通过界面完成，生产部署。

任一方式部署完都还「没装好」

本文只负责把服务跑起来（监听 :8787）。数据库、.env、管理员账号等初始化统一由安装向导完成，请勿手动改 .env 或导入 SQL。服务启动后请继续访问 → 运行安装向导。

一、环境要求（两种方式通用）

依赖版本用途
PHP>= 8.4运行时（Webman / Workerman 常驻内存）
MySQL>= 8.0主数据库，向导可自动建库
Redis>= 5.0缓存、会话、队列

PHP 必需扩展（安装向导的环境检测会逐项校验）：

扩展用途
pdo_mysqlMySQL 连接，ORM 底层依赖
redisRedis 连接，缓存/队列/会话依赖
opensslJWT 签名、密码哈希
zip备份打包、插件安装（ZipArchive）
gd验证码、缩略图裁剪
fileinfo文件 MIME 检测，上传安全校验

快速自检扩展是否齐全

php -m | grep -Ei 'pdo_mysql|redis|openssl|zip|gd|fileinfo'

缺哪个就在 php.ini 里去掉对应 ;extension=xxx 的行注释放开，重启 PHP 生效。

PHP必须要取消禁用的函数： shell_exec chown exec proc_open pcntl_exec pcntl_alarm pcntl_fork pcntl_waitpid pcntl_wait pcntl_signal pcntl_signal_dispatch putenv

仅源码方式额外需要：Composer、Node.js >= 20.19.0、pnpm >= 8.8.0。发行包方式无需这些，因为依赖与前端产物已内置。

建议使用宝塔服务器部署

尽量部署到linux系统上，程序更加稳定。

二、方式一：发行包一键部署（推荐）

发行包（形如 atrman_1.0.1_full.zip）由官方构建发布，已内置 vendor/ 后端依赖与编译好的管理前端 public/，基座程序固定。你不需要装 Composer、不需要 pnpm build，只要服务器有 PHP / MySQL / Redis，把包下载、解压、启动即可。

1. 准备环境

按上文「环境要求」装好 PHP（含扩展）、MySQL、Redis。数据库可以先不建——向导会用你填的库名自动 CREATE DATABASE。

2. 下载并解压

一键脚本（下载 → 解压 → 启动全自动，与首页终端展示的命令一致）：

curl -fsSL https://apps.atrman.com/app/am_store/install.sh | bash

占位命令

apps.atrman.com/app/am_store 为占位域名，官方安装脚本尚未发布；上线时请同步修改本页与首页终端（HomeArchitecture.vue）。

手动执行（效果与脚本完全相同）：从官方应用市场 / 交付渠道取得发行包，放到部署目录解压（包内是单顶层目录 atrman/）：

cd /www/wwwroot                       # 部署根位置，按你的环境自选
unzip atrman_1.0.1_full.zip       # 解压得到 /www/wwwroot/atrman/
cd atrman

关于「一键脚本」

发行包部署本质就是「下载 → 解压 → 启动」三步，没有任何依赖安装环节。一键脚本即替你串起这三步并自动 unzip 后 php start.php start -d；脚本不可用时，按下面手动命令执行效果完全相同。

3. 目录可写权限

runtime/（缓存/日志/安装锁）与 public/（上传/静态资源）需对运行用户可写：

chmod -R 755 runtime public
# 如以 www 用户运行：chown -R www:www runtime public

4. 启动

# Linux / macOS
php start.php start -d        # 守护模式（生产推荐）

# 前台调试（Ctrl+C 即停，日志直接打印到终端）
php start.php start

Windows 桌面环境（仅开发调试）可执行 php windows.php，自带文件监控自动重载。

服务默认监听 http://0.0.0.0:8787（worker 数为 cpu_count() * 4，并含 plugin_task 单进程调度插件定时任务）。看到监听成功后，打开浏览器继续 → 运行安装向导。

5. 常用运维命令

php start.php stop       # 停止
php start.php restart    # 重启（改了 .env / 配置后）
php start.php reload     # 平滑重载（改了常驻内存的注册代码）
php start.php status     # 运行状态

6.用域名访问

如果想用域名访问，可以用nginx反向代理http://127.0.0.1:8787这个端口即可，也可以通过宝塔创建一个反代项目，也可以参考第三种方式，宝塔部署。

三、方式二：源码部署（开发 / 二开）

需要改动基座代码、参与开发或调试时，从 git 源码构建。相比发行包，多了「装依赖」和「构建前端」两步。

1. 获取源码

git clone <仓库地址> atrman
cd atrman

2. 安装后端依赖

cd am-serve
composer install

生产环境可加 --no-dev --optimize-autoloader 精简依赖。

3. 构建管理前端

管理前端 am-web 的构建产物会回写到 am-serve/public/（详见 安装管理前端）：

cd ../am-web
pnpm install
pnpm build              # 产物回写到 am-serve/public/

开发热调试时不必每次 build，用 pnpm dev 起 Vite（自动代理到后端 :8787）即可。

4. 启动后端

cd ../am-serve
php start.php start     # 前台调试
# Windows 开发：php windows.php

5. 运行安装向导

浏览器访问 http://127.0.0.1:8787/install.html，后续与发行包方式完全一致 → 运行安装向导。

改了 PHP 代码不生效？

Webman 常驻内存，修改 PHP 代码后需 php start.php reload（平滑）或 restart（重启）才生效；Windows 下 windows.php 自带文件监控会自动重载。

四、宝塔部署（生产）

1. 下载源码

先下载完整源码何依赖到对应目录，解压后给对应的目录权限。

cd /www/wwwroot/atrman/am-serve
mkdir -p runtime/logs
chmod -R 755 runtime public
chown -R www:www runtime public

检测项一共三条：runtime/ 可写、public/ 可写、.env 可写（.env 还不存在时校验的是项目根目录可写，向导要把配置写进去）。

官方文档提到要 chmod -R 777 runtime，那是面板以 www 声明用户、实际按 daemon 启动导致的兼容操作。先用上面的 755 + chown www:www，仍报「不可写」再临时 777，装完改回来。

2. 添加站点（不用顺手建数据库）

网站 → 添加站点 → PHP项目 → 异步项目：

字段填写说明
域名你的域名先解析到本机
根目录/www/wwwroot/atrman解压后的位置
PHP 版本8.4低于 8.4 无法启动
数据库不创建安装向导会用你填的库名自动 CREATE DATABASE；手动建库容易和 .env 对不上
启动命令php start.php start不要加-d

MySQL、Redis 若也在面板装：记下 Redis 密码和端口，向导要填。

3. 设置运行目录为 /public

网站 → 设置 → 网站目录 → 运行目录 选 /public 并保存（源码方式是 /am-serve/public）。

这步不能省

运行目录留在根目录，config/、vendor/、.env 以及运行时生成的 secrets/（应用市场的包签名密钥）全部可被外网直接下载。

4. 设置伪静态（反向代理到 8787）

网站 → 设置 → 伪静态，粘贴：

# 将请求转发到 webman
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:8787;
    }
}

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

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

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

8787 就是 Atrman 的默认监听端口（am-serve/config/process.php 里 webman.listen）。改过监听端口的话，proxy_pass 要同步改。

四个 proxy_set_header 一个都别删

  • X-Forwarded-For / X-Real-IP：webman 的 getRealIp() 只在直连地址是内网时才采信代理头——宝塔反代恰好是这种情况。删掉后登录日志、操作日志里的 IP 全变成 127.0.0.1，ip2region 的归属地也跟着失效。
  • X-Forwarded-Proto：后台拼资源域名靠它（app/functions.php 的 assetDomain()）。开了 HTTPS 却没这个头，静态资源与 push 地址会被拼成 http://，混合内容报错。

5. 让面板守护进程

宝塔会替你守护 webman，启动命令填：

php /www/wwwroot/atrman/start.php start

千万不要加 -d

面板自己负责守护，-d 会把进程甩到后台后立即退出，面板判定启动失败——官方文档同样强调这一点。你的面板版本若没有这个输入框，就改用 软件商店 → 进程守护管理器 新建一条任务，命令与运行目录同上。

这一条命令会把 Atrman 的三个进程族一起拉起来：webman worker（cpu_count() * 4）、monitor、plugin_task。

不要另配宝塔「计划任务」

插件声明的定时任务由 plugin_task 单进程调度（任务体带 Redis 锁兜底）。再在面板「计划任务」里挂一条 crontab 调用后台接口，就是同一业务跑两遍。

生产可选：关掉文件监控

monitor 的 enable_file_monitor 判定条件是「命令行里有没有 -d」（am-serve/config/process.php 的 monitor.options）。宝塔守护方式必然不带 -d，于是文件监控 + 内存巡检都是开着的：改 PHP / config / .env 会触发自动重启，这在生产属于意外行为。建议显式改成 'enable_file_monitor' => false，改完用面板重启生效。

6. 防火墙只放 80 / 443

webman.listen 绑的是 0.0.0.0:8787。面板 安全 → 系统防火墙 和云厂商安全组里都不要放行 8787：直连端口能绕过伪静态的 .php / 隐藏文件拦截，也能绕过 nginx 层的限流，爆破和扫描会直接打到应用上。需要临时排查时再放行，用完关掉。

7. 重启站点并运行安装向导

面板里重启该站点（或守护进程列表点重启），然后浏览器访问：

http://你的域名/install.html

→ 运行安装向导。不要自己新建 .env，也不要手动导入 install/install.sql、install/seed.sql——向导负责写 .env（并设成 0644）、建表、建管理员账号。

11. 常见故障

现象先查
502 Bad Gateway进程是否真在跑；runtime/logs/workerman.log 与 runtime/logs/stdout.log；proxy_pass 端口是否与 webman.listen 一致
启动失败 / 起来就退启动命令多加了 -d；php -m 缺 pcntl/posix；禁用函数没删干净（pcntl_fork、putenv 是向导必检项）
改了 PHP 代码不生效用面板重启。不要在 SSH 里 php start.php restart -d，会和面板守护抢同一份 pid；monitor 开着时改代码会自动重载，无需手动
install.html 404第 6 步运行目录没设成 /public
装插件报解压失败 / 上传失败zip 扩展、fileinfo 扩展；runtime/、public/ 是否可写
大包上传中断单包上限 50MB，改走后台「文件库引用」选包
Redis 连不上、缓存行为异常.env 里 Redis 端口/密码与面板 Redis → 设置 一致；DB_PREFIX 区分大小写，别手敲
后台显示正常但刷新白屏 / 混合内容第 7 步的 X-Forwarded-Proto 头缺失，或证书没配

下一步

三种方式服务跑起来后，都进入同一初始化流程：→ 运行安装向导

最近更新: