宝塔API需先在面板设置中开启并生成密钥,调用时必须用key、secret、时间戳、路径及排序后参数拼接签名;仅支持HTTPS,超时建议设30秒以上,路径须规范。

宝塔API怎么开启和获取密钥
不开启API,所有自动化都无从谈起。默认安装后API是关闭的,且没有密钥——直接调用会返回 {"code":400,"msg":"API未开启"}。
操作路径:面板首页 → 「设置」→ 「面板设置」→ 拉到底部勾选「开启API接口」→ 点击「保存」→ 再点「API密钥管理」生成新密钥。
- 生成后务必复制保存
key和secret,页面刷新后secret不再显示(无法找回) -
key是公开的,secret必须严格保密,别硬编码进前端或Git仓库 - 如果误删密钥,只能重新生成,旧脚本会立刻失效
调用API前必须算签名(sign)
宝塔API不是简单带token的REST请求,每次请求都要在URL里带上动态 sign 参数,它是用 key、secret、当前时间戳(秒级)、请求路径和参数拼起来SHA256加密的结果。
漏掉时间戳校验或签名错一位,就会返回 {"code":401,"msg":"签名错误"},这是最常卡住人的地方。
- 时间戳必须是UTC+8的秒级整数(
int(time.time())),不能带毫秒,服务器时间误差超过5分钟也会失败 - 拼接字符串顺序固定:
key + secret + timestamp + path + ? + query_string(按字母序排序参数) - GET请求的参数要参与签名;POST的body数据(如JSON)不参与,但path和query仍要算
示例(Python):sign = hashlib.sha256((key + secret + str(timestamp) + path + '?' + 'app_name=nginx&status=start').encode()).hexdigest()
常见操作对应的关键接口和参数
别盲目翻文档,高频动作就那几个,直接记住路径和必填字段更省事:
- 重启网站:
/site/restart_site,POST body需含{"siteName": "example.com"} - 获取PHP版本列表:
/php/get_php_version,GET即可,不用传参数 - 添加计划任务:
/crontab/add_crontab,POST body里name、type(hour/day等)、where1(具体时间值)、sname(脚本路径或命令)都不能为空 - 查MySQL数据库列表:
/database/get_database_list,GET加type=mysql查询参数
注意:/ssl/get_ssl_list 返回的是证书ID而非域名,要查某个域名是否已部署SSL,得先用 /site/get_sites 拿站点列表,再逐个看 ssl_id 字段。
HTTPS、超时、错误码这些实际跑起来才踩的坑
本地测试通了,一上生产就报错?大概率是这几个点没对齐:
- 宝塔API只支持HTTPS请求,HTTP会直接被Nginx 301跳转,导致签名失效(跳转后URL变了,sign没重算)
- 默认超时是3秒,执行慢的操作(比如备份大网站)容易触发
{"code":504,"msg":"网关超时"},建议客户端设成30秒以上 -
code为0才是成功,非0不全是错误——比如{"code":1001,"msg":"站点不存在"}是业务提示,不是网络异常 - 部分接口(如
/files/get_files_list)要求路径用正斜杠且以/www/wwwroot/开头,传../或反斜杠会返回空列表不报错
签名逻辑、时间同步、HTTPS强制、路径规范——这四点没对齐,90%的“调不通”问题就出在这儿。
大量免费API接口:立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游,为数据API应用能力赋能!










