宝塔面板API对接指南：自助建站PHP源码自动化部署与二次开发实战

简介：这套2021年PHP自助建站系统源码，是一套基于宝塔面板开发的全开源自助搭建网站平台，适合站长、开发者及建站服务商用于搭建建站业务或学习二次开发。系统基于PHP+MYSQL开发，内置论坛、博客、官网等30多套网站程序模板，前台用户注册后即可在线购买模板，一键完成网站部署。后台支持网站管理、自定义域名、SSL管理、重装还原、多服务器集群管理，并集成易支付、码支付、微信官方支付与支付宝官方支付，覆盖自助建站全流程。资源包共786个文件、17.18MB，包含png图片、php脚本、js脚本、scss样式、css样式、ttf字体等，目录结构清晰，便于定位后台程序、前端模板和SQL数据库文件。已有1091人学习下载，适合具备PHP基础、希望研究宝塔面板对接和自动化建站机制的中高级学习者。

1. 与其让建站工单排队，不如把这套自助建站 PHP 源码直接丢给用户

做服务器代售、虚拟主机销售，或者在公司里管着一堆业务站点的运维，应该都对同一件事有感觉：开站这个操作本身不难，但架不住量大、零碎、还要等人工。用户下单后问“网站什么时候好”，技术这边得先去面板建站、开库、配 PHP 版本、绑域名，一个站下来没有十几次点击根本起不来。这套宝塔自助建站系统源码就是来解决这个环节的：用户端是 PHP 写的自助开通页面，注册登录之后选套餐、填域名、点创建，系统调宝塔面板的开放 API，自动完成建站、建库、绑定域名这些动作，全程十几秒。部署在宝塔 LNMP 环境就能跑，运维只需要把 API 密钥配好，后续基本不用再管开站工单。适合有少量 Linux 基础、想把手头建站流程自动化的人，也适合做模板站、企业站批量交付的小团队。

2. 部署这套源码：环境、目录结构与上线前的参数核对

2.1 运行环境与目录结构

这套源码是 PHP 实现，官方跑法就是宝塔面板自家环境：Nginx + PHP 7.4（或 8.0/8.1）+ MySQL 5.7。PHP 版本别低于 7.2，因为代码里用了??空合并运算符和类型声明，换到 5.x 会直接报语法错误。MySQL 用 5.7 或者 8.0 都行，表结构没有特殊依赖，utf8mb4 字符集记得选上。

源码包解压后的布局大致是这样：

bt-builder/ ├── app/ │ ├── Controllers/ // 用户端和后台控制器 │ ├── Services/BtApi.php // 宝塔API封装 │ └── Models/ // 数据模型 ├── config/ │ ├── database.php // 数据库连接配置 │ └── bt.php // 宝塔API密钥与面板地址 ├── public/ │ └── index.php // 入口文件 ├── install/ │ └── install.sql // 初始表结构 └── .env // 环境变量，含敏感密钥

拿到源码第一件事不是丢进站点目录，而是先看config/database.php和install/install.sql里的表结构。这套系统的核心数据表不多，用户表、套餐表、站点表、订单表、API 日志表，加起来五张左右。搞清楚这几张表之间的关系，后面二开会顺手很多。

2.2 初始化：导入 SQL 并改配置

在宝塔面板里先建一个数据库，比如sites_builder，然后导入install/install.sql。接着打开config/database.php，把数据库连接信息改成实际值：

return [ 'host' => '127.0.0.1', 'port' => 3306, 'dbname' => 'sites_builder', 'username' => 'builder_user', 'password' => '改成你自己的随机密码', 'charset' => 'utf8mb4', ];

再打开config/bt.php，这是整个系统能不能跑起来的关键。宝塔面板开启 API 的位置在「面板设置 → API接口」，进去之后生成一套 app_key 和 app_secret。注意面板 API 的请求路径是面板端口下的/data/api.json，跟浏览器访问面板用的安全入口不是一回事。

return [ 'panel_url' => 'http://127.0.0.1:8888', 'app_key' => '你生成的app_key', 'app_secret' => '你生成的app_secret', 'default_php' => '74', 'default_path' => '/www/wwwroot', ];

这里有个容易踩的细节：panel_url里的地址不要从浏览器地址栏复制粘贴，浏览器里会带面板安全入口的路径，而 API 调用是另一套路径，通常直接写http://IP:端口就行。面板 API 那里还有个 IP 白名单设置，建议先填127.0.0.1，等确认系统跑通了再放行业务服务器地址。

提示：config/bt.php和.env里保存的是面板主权限密钥，务必把文件权限设为 600（chmod 600），Web 目录下其他用户不要给写权限。

2.3 入口配置与连通性验证

把public/作为站点运行目录，或者把源码放到站点目录后设置伪静态，让所有请求都走index.php入口。Nginx 伪静态规则：

location / { try_files $uri $uri/ /index.php?$query_string; }

改完伪静态访问站点，正常会看到安装检测页，检测目录权限、PHP 扩展和数据库连接。这套源码没有复杂的 Composer 依赖，核心是 PHP 的 curl 扩展，检测时重点确认curl、json、mysqli、openssl四个扩展都是开启状态。

部署完成后我习惯先做一次 API 连通性验证，确认密钥和签名流程没问题再开放前台注册。用 shell 直接测最直观：

TS=$(date +%s%3N) RT=$(echo -n "${TS}haoshu" | md5sum | cut -d' ' -f1) SIGN=$(echo -n "${RT}你的app_secret" | sha256sum | cut -d' ' -f1) curl -s -X POST http://127.0.0.1:8888/data/api.json \ -d "request_token=${RT}" \ -d "request_time=${TS}" \ -d "request_token_sha256=${SIGN}"

这条命令里的TS是毫秒时间戳，RT是 md5 出来的 request_token，SIGN是 request_token 加 app_secret 的 SHA256 值。如果响应头里能看到X-Request-Token，说明密钥和签名流程没问题，再去接前端。注意sha256sum输出的十六进制是小写，PHP 的hash('sha256')也是小写，两边对得上。

3. 核心逻辑拆解：PHP 怎么把「点按钮」变成「自动开站」

3.1 宝塔 API 认证：token 的获取方式

宝塔 API 跟常规 REST API 不太一样，不能拿着 app_key 直接请求建站接口，得先请求一次/data/api.json换 token，后续接口在请求头里带上 token 才有权限。这个机制和大多数 PHP 后台系统的登录态设计类似，只是 token 在响应头里返回，不在 body 里。

具体流程：每次请求先拼一个request_token，这个字符串可以自定义，但通常用毫秒时间戳加随机串做 md5；然后按 app_secret 给请求签名；最后把 token 从响应头里取出来供后续使用。我封装了一个 BtApi 服务，核心代码长这样：

public function getToken(): string { $time = time() * 1000; $secret = $this->secret; $requestToken = md5($time . 'haoshu'); $data = [ 'request_token' => $requestToken, 'request_time' => $time, 'request_token_sha256' => hash('sha256', $requestToken . $secret), ]; $ch = curl_init($this->panelUrl . '/data/api.json'); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, $data); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_HEADER, 1); curl_setopt($ch, CURLOPT_TIMEOUT, 10); $response = curl_exec($ch); $headerSize = curl_getinfo($ch, CURLINFO_HEADER_SIZE); $header = substr($response, 0, $headerSize); curl_close($ch); if (preg_match('/X-Request-Token:\s*([a-zA-Z0-9]+)/i', $header, $match)) { return trim($match[1]); } throw new RuntimeException('获取宝塔Token失败，请检查面板地址和密钥'); }

逻辑说明：request_token用time() * 1000加固定盐值做 md5，保证每次请求都不一样；request_token_sha256是 request_token 加 app_secret 的哈希，相当于给换取 token 的请求本身签了名。参数里CURLOPT_HEADER设为 1 是让 curl 把响应头一并返回，这样才能从 header 里截取 token；CURLOPT_TIMEOUT给 10 秒，面板 API 在高负载下响应会慢，但超过 10 秒基本就是面板侧卡住了，不值得继续等。

3.2 创建站点：一次建站要拼好 webname 参数

拿到 token 之后就可以调建站接口了。创建站点对应POST /site?action=AddSite，它需要的参数比想象中多一些：

public function addSite(string $domain, string $path, int $phpVersion = 74): array { $token = $this->getToken(); $webname = json_encode([ 'domain' => $domain, 'domainlist' => [], 'Index' => 0, 'type' => 'PHP', ]); $post = [ 'webname' => $webname, 'path' => $path, 'type_id' => 0, 'version' => $phpVersion, 'port' => 80, 'ps' => '自助开通', 'ftp' => 0, 'sql' => 0, ]; $ch = curl_init($this->panelUrl . '/site?action=AddSite'); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($post)); curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-Request-Token: ' . $token]); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_TIMEOUT, 15); $response = curl_exec($ch); curl_close($ch); $result = json_decode($response, true); if (($result['status'] ?? false) !== true) { throw new RuntimeException($result['msg'] ?? '建站返回未知错误'); } return $result; }

webname是一个 JSON 字符串，里面domainlist是附加域名数组，Index为 0 代表用主域名作为目录归属，type固定PHP。version是 PHP 版本内部 ID，74 对应 PHP 7.4，80 对应 8.0。这个映射关系是宝塔面板内部约定的，不同面板版本可能有差异，部署后建议手动在面板里建一个站，对照日志确认实际接受的版本号格式。

代码里用http_build_query做参数序列化是必要的。宝塔 API 对 POST 参数的解析依赖 urlencoded 格式，直接传数组在部分 PHP 配置下会解析异常，这个坑比较隐蔽。sql参数这里先给 0，意味着不同时创建数据库；如果套餐里包含数据库，需要单独调建库接口，下一节讲。

3.3 建库与密码生成：数据库参数不能写死

需要给用户开数据库时，请求POST /database?action=AddDatabase，至少需要name、db_user、db_pwd、codeing、db_type这几个参数：

public function addDatabase(string $dbName, string $dbUser, string $dbPwd): array { $token = $this->getToken(); $post = [ 'name' => $dbName, 'db_user' => $dbUser, 'db_pwd' => $dbPwd, 'codeing' => 'utf8mb4', 'db_type' => 'MySQL', 'dataAccess'=> 'localhost', ]; $ch = curl_init($this->panelUrl . '/database?action=AddDatabase'); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($post)); curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-Request-Token: ' . $token]); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_TIMEOUT, 15); $response = curl_exec($ch); curl_close($ch); $result = json_decode($response, true); if (($result['status'] ?? false) !== true) { throw new RuntimeException($result['msg'] ?? '创建数据库失败'); } return $result; }

数据库密码不要写死，我一般用随机生成器，每次创建都生成独立密码：

function randomDbPwd(int $length = 16): string { $chars = 'abcdefghijkmnpqrstuvwxyzABCDEFGHJKMNPQRSTUVWXYZ23456789'; $str = ''; for ($i = 0; $i < $length; $i++) { $str .= $chars[random_int(0, strlen($chars) - 1)]; } return $str; }

这个生成器排掉了容易混淆的字符（l、o、0、1），生成的密码即使被打印在工单消息里，抄写时也不会出错。生成后把数据库名、用户名、密码、站点路径统一写进bt_sites表，用户后续在个人中心能看到完整信息。

最后一步是更新站点记录状态并给用户发送开通通知。整套流程下来一般在 5 秒内完成。如果某一步失败，建议在bt_api_logs表里记录请求参数和面板返回的原文。这个习惯特别重要，线上跑起来之后，日志就是排查问题的第一手资料。

4. 二次开发指南：套餐、配额与域名白名单怎么改

4.1 套餐表结构与配额判定

默认表结构里有一张bt_plans套餐表，控制用户能开几个站、几个库。核心字段用表列一下：

用户下单后套餐和用户绑定，配额判断在创建站点的入口做。注意一个点：配额校验必须放后端，不能依赖前端 JS。我见过有同事把限制写在页面脚本里，结果被用户直接 post 请求打穿，一口气建了十几个站，最后才在接口层补上后端校验。

public function checkQuota(int $userId, int $planId): bool { $plan = PlanModel::find($planId); if (!$plan) return false; if ($plan->site_limit > 0) { $count = SiteModel::where('user_id', $userId)->count(); if ($count >= $plan->site_limit) return false; } return true; }

4.2 域名绑定数量与格式校验

如果要做“一个站点绑定多个域名”的业务，可以在addSite之前加一层域名数量和格式校验。我的做法是把用户提交的域名数组解析出来，比对套餐表里的domain_limit，超过就拒绝创建并返回明确提示：

public function validateDomainLimit(array $domains, int $planId): void { $limit = PlanModel::where('id', $planId)->value('domain_limit'); if ($limit > 0 && count($domains) > $limit) { throw new InvalidArgumentException( '当前套餐最多绑定 ' . $limit . ' 个域名，你提交了 ' . count($domains) . ' 个' ); } foreach ($domains as $domain) { if (!preg_match('/^([a-z0-9-]+\.)+[a-z]{2,}$/i', $domain)) { throw new InvalidArgumentException('域名格式不合法: ' . $domain); } } }

这个正则把https://、斜杠、星号都挡在了门外，防止有人把路径直接拼进域名参数。之前有个翻车现场，就是用户提交了带../的内容，路径段被拼到站点目录里，虽然没有提权风险，但目录结构被搞乱了，加了这个校验之后同类问题再没出现过。域名校验要做两端，前端做格式提示是为了体验，后端做强制校验才是安全边界。

4.3 失败回滚：别让半成品站点挂在面板上

自助建站是多个 API 请求的组合：先建站、再建库。如果建库那一步失败，站点已经留在面板里了，用户看到的结果是“报错但网站确实存在了”。正确做法是记录当前执行到的步骤，失败时调用删除接口回滚：

$siteResult = $btApi->addSite($domain, $path, $phpVersion); $siteId = $siteResult['data']['id'] ?? 0; try { $dbResult = $btApi->addDatabase($db, $dbUser, $dbPwd); } catch (Exception $e) { if ($siteId > 0) { $btApi->deleteSite((int)$siteId); } throw $e; }

删除接口对应宝塔 API 的POST /site?action=DeleteSite，参数传站点id。这样用户重新点击创建时，不会遇到“站点已存在”的残留问题。回滚时还要注意一点：删除站点时宝塔默认保留文件目录，如果不想留在磁盘上，要看清楚 DeleteSite 的参数说明，把删除目录和数据库的选项一并传上，避免白白占着磁盘空间。

5. 避坑：从对接宝塔 API 到上线，这五个坑值得记下来

5.1 Token 取不到，接口一直 403

现象：前台点击创建，日志记录的是403 Forbidden，请求根本没到建站逻辑。

原因：getToken()里解析响应头的正则跟面板实际返回格式对不上。面板返回的是X-Request-Token: xxx，但正则匹配时把空格也带进去了，请求头拼接后变成X-Request-Token: xxx，宝塔侧解析失败直接拒绝。

解决：正则改成'/X-Request-Token:\s*([a-zA-Z0-9]+)/i'，取出来后trim()一下。最好把响应 header 原样记录到日志，排查时一眼就能看到问题。

5.2 站点创建成功但网站打不开

现象：建站接口返回成功，用户访问域名却看到默认欢迎页，或者 PHP 代码被当作纯文本输出。

原因：version参数传了 74，但当前面板版本识别的 PHP 版本 ID 不是 74。宝塔不同面板大版本里，PHP 版本内部编号并不一致，有的面板要用PHP-74这种字符串，有的用纯数字 ID。

解决：部署后先手动在面板里点一次创建站点，再去看面板数据库里sites表的php_version字段，或者翻事件日志确认实际请求参数，把映射关系确认后写进配置。不要想当然地认为 74 一定对应 PHP 7.4。

5.3 数据库创建成功但程序连不上

现象：数据库建出来了，业务程序连接时报 access denied。

原因：宝塔 API 创建数据库后，权限默认只授予了localhost的主机访问。如果 PHP 业务代码部署在另一台服务器上，或者用户填的数据库地址是公网 IP，授权主机不匹配就连不上。另一个常见原因是密码里有#、$这类字符，在 shell 拼接时被转义掉，实际存进去的密码跟显示的不一样。

解决：数据库地址和授权主机要统一，或者直接授权%通配；密码生成时避开 shell 特殊字符。前面给的字符集已经排除了全角符号和特殊字符，够用。

5.4 用户重复点击，同一个域名被创建两次

现象：创建按钮没做防抖，用户双击或网络慢时重复提交，同一个域名在面板里出现两条站点记录，或者第二次请求返回“域名已存在”。

原因：前端按钮没有 disabled 状态，后端也没有做幂等控制。宝塔 API 本身对已存在域名会拒绝，但报错时机不稳定。

解决：三件事一起做。前端点击后按钮置灰；后端在bt_sites表给domain字段加唯一索引；进addSite之前先查库，存在就直接返回“该域名已开通”，不再重复调 API。

5.5 API 密钥泄漏，被刷建站

现象：服务器上多了一批不认识的站点目录，面板登录日志显示异常 IP。

原因：config/bt.php的密钥写死在 PHP 文件里，站点目录被设置成了 777 权限，源码包在传输过程中也没做加密，密钥跟着一起泄露。

解决：密钥独立放到.env文件，.env权限设为 600，并且配置 Nginx 禁止访问点开头的文件；宝塔面板 API 接口开启 IP 白名单，只允许本机或内网地址调用；在bt_api_logs表里加上请求 IP 字段，出现异常调用能第一时间定位来源。

6. 上线前加一道保险：给创建接口加签名与限流

自助建站系统上线后，最容易被人盯上的不是宝塔 API 本身，而是对外暴露的创建接口。如果让用户直接请求create_site，随便写个脚本就能批量刷建站，轻则把服务器资源耗光，重则导致整个面板被封。所以我在创建接口前加了一个签名校验层，前端发起创建请求时用当前时间戳和 shared_key 生成签名，后端验签通过才进入建站逻辑。整个过程不需要引入复杂的 OAuth，一个简易签名就够了。

public function verifySign(array $params, string $sharedKey): bool { $timestamp = $params['timestamp'] ?? 0; if (abs(time() - (int)$timestamp) > 300) { return false; } $checkStr = $sharedKey . $params['user_id'] . $params['domain'] . $timestamp; return hash_equals($params['sign'] ?? '', md5($checkStr)); }

sharedKey同时存在于前端配置和后端.env，不在浏览器里明文出现。timestamp防重放，超过 5 分钟的请求直接丢弃。hash_equals做常量时间比较，避免时序攻击，别用==直接比较。

限流我一般用 Redis 计数器实现，在入口加一层每分钟请求次数限制。用 Redis 的 INCR 和 EXPIRE 最方便：

$key = 'site_create:' . $userId . ':' . date('i'); $count = $redis->incr($key); if ($count === 1) { $redis->expire($key, 60); } if ($count > 3) { throw new RuntimeException('每分钟最多创建3个站点，请稍后再试'); }

频率放到 3 次/分钟，手动测试也够用，批量刷直接被弹回去。做完签名和限流这两件事，系统才算真正能放在公网环境跑。

从那以后我每次部署这套自助建站源码，都会强制把签名校验、限流、密钥权限三项检查走一遍，再开放前台注册，这三件事在源码里默认可能没做得那么完整，上线前最好自己补上。希望这篇拆解能帮你在部署和二次开发时少走几步弯路，一步步跑通它。

本文还有配套的精品资源，点击获取