宝塔面板部署

★ 前置条件

已安装宝塔面板
已在 1Panel 中通过“网站”功能创建 PHP 运行环境网站
已完成域名解析和 SSL 证书配置

★ 切换宝塔 Nginx

宝塔默认安装的 Nginx 是纯净版，不包含 Lua 模块。如果不装 OpenResty 或者手动给 Nginx 编译加入 Lua 支持，遇到 lua_shared_dict 或 access_by_lua_block 这种指令，Nginx 在 nginx -t 检查语法时就会直接报错 _unknown directive_，根本启动不了。

因此，想要在宝塔面板上运行此服务，你必须安装 OpenResty 或者手动编译 Lua 模块作为 Web 服务器，不能使用宝塔默认的 Nginx 。

警告：如果你在纯 Nginx 下强行粘贴上述配置，执行 nginx -t 会直接报错崩溃！

★ 宝塔路径与 URL 区分

概念	格式 / 示例	使用场景
宝塔目录名	`IP_端口` → `xx.xx.xx.xx_yyy` `网址` → `www.123.com`	仅用于文件系统路径
网络 URL	`http(s)://IP:端口` → `http://xx.xx.xx.xx:yyy` `http(s)://www.123.com` → `http://www.123.com`	仅用于浏览器访问或代码中拼接域名

一、上传源码

创建网站在宝塔面板中点击 “网站” → “添加站点”

域名：填写你的域名，如果没有域名，填写 IP:端口

PHP版本：选择你安装的 PHP 版本（如 PHP-8.2）

数据库：纯静态（不创建）

index.html

nurl-key

nurl

二、编辑配置

1. config.php

打开文件 /www/wwwroot/{你的域名}/api/config.php 进行修改：

警告：注意修改高亮行内容。

<?php
return [
    // 短链域名
    'domain'           => 'https://{你的域名}',  // 改为你的短链域名，用于拼接完整短链

    // 前端面板域名（用于 CORS，与短链跳转域名独立）
    // 如果前端面板与短链服务部署在不同域名，请改为面板实际域名（如 https://panel.example.com）
    // 未配置时回退使用 domain，保持向后兼容
    'panel_origin'     => '',

    // 前端面板总开关
    // false 时 PHP 层直接返回 403，前端不再可访问（短链跳转不受影响）
    'panel_enabled'    => true,

    // 时区偏移（ISO 8601 格式）
    // 影响过期时间的显示和计算
    'tz_offset'        => '+08:00',

    // 冷存储 JSON 文件路径
    'perm_path'        => __DIR__ . '/../backend/data/perm.json',  // 永久短链数据文件
    'temp_path'        => __DIR__ . '/../backend/data/temp.json',  // 临时短链数据文件

    // API Key 存储
    'keys_path'        => __DIR__ . '/../backend/data/keys.json',  // Key 存储文件
    'key_ttl_days'     => 7,                                       // 常驻 Key 有效期（天）
    'onetime_pool_size' => 20,                                     // 一次性 Key 池大小

    // 数量限制，本服务最大上限均为 9999
    'perm_limit'       => 9999, // 永久短链
    'temp_limit'       => 9999, // 临时短链

    // TTL 上限，临时短链最长存活时间（秒），默认 1 年
    'ttl_max'          => 365 * 24 * 3600,

    // 保留短码（与 nginx 路由前缀对齐，禁止用户注册为自定义短码）
    // 新增路由时需同步更新此列表
    'reserved_codes'   => ['api', 'stat', 'admin', 'data', 'lua', 'headless', 'internal'],

    // 内部 OpenResty API 地址（仅本地 18500 端口，不对外暴露）
    // 如果你的 PHP 是直接部署的，保持 127.0.0.1 即可
    'internal_host'    => 'http://127.0.0.1:18500',  //具体内网地址请自行查阅！
    'internal_timeout' => 2.0,                       //内部接口请求超时时间（秒）
    'internal_token_path' => __DIR__ . '/../backend/data/internal_token',
    'internal_token'      => trim(@file_get_contents(__DIR__ . '/../backend/data/internal_token') ?: ''),
];
?>

三、修改 OpenResty 主配置

使用 1Panel 面板的文件管理打开文件：

/{1Panel安装目录}/apps/openresty/{openresty容器名}/conf/nginx.conf

在 http 块开头（include mime.types; 之前）添加以下内容：

警告：注意修改高亮行内容。

    # ═══════════════════════════════════════════════════
    # 声明共享字典和限流区域
    # ═══════════════════════════════════════════════════

    # ———— 共享字典 ——————————————————————————————————————
    lua_shared_dict su_url       4m;
    lua_shared_dict su_exp       2m;
    lua_shared_dict su_meta      1m;
    lua_shared_dict su_blocklist 1m;

    # ———— API 限流：每 IP 每分钟 30 次请求 ————————————————
    limit_req_zone $binary_remote_addr zone=api:10m rate=30r/m;

    # ———— 跳转限流：每个 IP 每秒 2 次，突发 10 次 ——————————
    limit_req_zone $binary_remote_addr zone=redirect_burst:10m rate=2r/s;

    # ———— Worker 初始化：注册定时器（每次 worker 启动/reload 均执行）————
    # 注意：init_worker_by_lua_block 中 ngx.var 不可用，配置通过 config.lua 读取
    # expire_sweep 定时器在此注册，确保 nginx reload 后定时器不丢失
    init_worker_by_lua_block {
        package.path = "/www/wwwroot/{你的域名}/backend/lua/?.lua;;;" .. package.path
        local init = require "shorturl.init"
        init.init_worker()
    }

    # ═══════════════════════════════════════════════════
    # 内部 Lua API（仅本地访问）
    # ═══════════════════════════════════════════════════
    server {
        # 仅绑定回环地址；若需 Docker bridge 访问，追加第二行：
        #   listen <docker网桥IP>:18500;
        listen 127.0.0.1:18500;
        server_name _;

        location /internal/ {
            allow 127.0.0.1;
            allow 172.18.0.0/16;  # 请将 172.18.0.0/16 替换为你实际的 Docker 网桥子网
            deny all;

            content_by_lua_block {
                package.path = "/www/wwwroot/{你的域名}/backend/lua/?.lua;;;" .. package.path
                local internal = require "shorturl.internal"
                internal.dispatch()
            }
        }
    }
# ═══════════════════════[END]═════════════════════════

插入示例：

    ...前面保持不变...

events {
      use epoll;
      worker_connections 5120;
      multi_accept on;
}

http {
    # ═══════════════════════════════════════════════════
    # 声明共享字典和限流区域
    # ═══════════════════════════════════════════════════
    ....在此处添加...
    #══════════════════════[END]═════════════════════════

    include       mime.types;
    default_type  application/octet-stream;

    ...后面保持不变...

四、修改站点 Nginx 配置

这是最关键的一步。1Panel 创建网站时会自动生成一份 Nginx 配置，我们需要在保留 1Panel 自动生成的 Nginx 配置基础上添加 Short_NURL 所需的配置。

请从 1Panel 面板的“网站”界面进入你的网站，编辑 Nginx 配置。

警告：注意修改高亮行内容。

站点 Nginx 配置

    # ═══════════════════════════════════════════════════
    # ★ 新增配置
    # ═══════════════════════════════════════════════════

    # ★ 业务参数
    set $su_php_fpm          "127.0.0.1:9000";   # PHP-FPM 监听地址，按实际环境修改
    set $su_domain           "https://{你的域名}";
    set $su_tz_offset        "+08:00";
    set $su_perm_path        "/www/wwwroot/{你的域名}/backend/data/perm.json";
    set $su_temp_path        "/www/wwwroot/{你的域名}/backend/data/temp.json";
    set $su_expire_interval  3600;
    set $su_redirect_code    302;

    # ★ 安全响应头（补充 ShortURL 需要的）
    add_header X-Content-Type-Options  "nosniff"          always;
    add_header X-Frame-Options         "DENY"             always;
    add_header Referrer-Policy         "no-referrer"      always;

    # ★ 屏蔽敏感目录
    location ^~ /data/ {
        deny all;
        return 404;
    }
    location ^~ /lua/ {
        deny all;
        return 404;
    }
    location ^~ /backend/ {
        deny all;
        return 404;
    }
    location ^~ /api/common/ {
        deny all;
        return 404;
    }
    location ^~ /api/key/ {
        deny all;
        return 404;
    }
    location ^~ /api/lua/ {
        deny all;
        return 404;
    }
    location ^~ /api/storage/ {
        deny all;
        return 404;
    }
    location ^~ /headless/ {
        deny all;
        return 404;
    }
    # ^~ 前缀匹配，拦截所有 /internal/* 路径（不仅是精确的 /internal/）
    location ^~ /internal/ {
        deny all;
        return 404;
    }

    # ★ API 路由 → PHP-FPM
    # 覆盖下方原有的 PHP location，API 请求不走默认 PHP 处理
    location ^~ /api/ {
        limit_req zone=api burst=5 nodelay;

        location = /api/create {
            limit_except POST { deny all; }
            fastcgi_pass $su_php_fpm;
            fastcgi_index index.php;
            fastcgi_param SCRIPT_FILENAME /www/wwwroot/{你的域名}/api/routes/create.php;
            include fastcgi_params;
        }

        location = /api/delete {
            limit_except POST { deny all; }
            fastcgi_pass $su_php_fpm;
            fastcgi_index index.php;
            fastcgi_param SCRIPT_FILENAME /www/wwwroot/{你的域名}/api/routes/delete.php;
            include fastcgi_params;
        }

        location = /api/list {
            limit_except GET { deny all; }
            fastcgi_pass $su_php_fpm;
            fastcgi_index index.php;
            fastcgi_param SCRIPT_FILENAME /www/wwwroot/{你的域名}/api/routes/list.php;
            include fastcgi_params;
        }

        location = /api/stat {
            limit_except GET { deny all; }
            fastcgi_pass $su_php_fpm;
            fastcgi_index index.php;
            fastcgi_param SCRIPT_FILENAME /www/wwwroot/{你的域名}/api/routes/stat.php;
            include fastcgi_params;
        }

        location = /api/ping {
            limit_except GET { deny all; }
            fastcgi_pass $su_php_fpm;
            fastcgi_index index.php;
            fastcgi_param SCRIPT_FILENAME /www/wwwroot/{你的域名}/api/ping.php;
            include fastcgi_params;
        }
    }

    # ★ 无头链路路由 → PHP-FPM（nurl-key 远程管理工具使用）
    location ^~ /headless/api/ {
        limit_req zone=api burst=5 nodelay;

        location = /headless/api/create {
            limit_except POST { deny all; }
            fastcgi_pass $su_php_fpm;
            fastcgi_index index.php;
            fastcgi_param SCRIPT_FILENAME /www/wwwroot/{你的域名}/headless/create.php;
            include fastcgi_params;
        }

        location = /headless/api/delete {
            limit_except POST { deny all; }
            fastcgi_pass $su_php_fpm;
            fastcgi_index index.php;
            fastcgi_param SCRIPT_FILENAME /www/wwwroot/{你的域名}/headless/delete.php;
            include fastcgi_params;
        }

        location = /headless/api/list {
            limit_except GET { deny all; }
            fastcgi_pass $su_php_fpm;
            fastcgi_index index.php;
            fastcgi_param SCRIPT_FILENAME /www/wwwroot/{你的域名}/headless/list.php;
            include fastcgi_params;
        }

        location = /headless/api/stat {
            limit_except GET { deny all; }
            fastcgi_pass $su_php_fpm;
            fastcgi_index index.php;
            fastcgi_param SCRIPT_FILENAME /www/wwwroot/{你的域名}/headless/stat.php;
            include fastcgi_params;
        }

        # ~* 大小写不敏感，与其他接口对齐；PHP 侧已做 strtolower
        location ~* "^/headless/api/get/([0-9a-zA-Z-]{1,4})$" {
            limit_except GET { deny all; }
            fastcgi_pass $su_php_fpm;
            fastcgi_index index.php;
            fastcgi_param SCRIPT_FILENAME /www/wwwroot/{你的域名}/headless/get.php;
            fastcgi_param PATH_INFO       /$1;
            include fastcgi_params;
        }
    }

    # ————★ 一次性数据加载（惰性触发）————————————————————————————————
    # 每个 worker 首次请求时执行冷启动（从 JSON 加载到 shared dict），后续请求跳过
    # 注意：定时器注册已移至 init_worker_by_lua_block（见主配置），此处仅负责数据加载
    access_by_lua_block {
        package.path = "/www/wwwroot/{你的域名}/backend/lua/?.lua;;;" .. package.path
        local su_meta = ngx.shared.su_meta
        if not su_meta:get("inited_" .. ngx.worker.id()) then
            math.randomseed(ngx.time() + ngx.worker.id())
            local init = require "shorturl.init"
            init.init()
            su_meta:set("inited_" .. ngx.worker.id(), 1)
        end
    }

    # ★ 短链跳转（最低优先级，匹配 1-4 位小写字母数字）
    # 正则中的花括号必须用双引号包裹，否则 Nginx 会报错
    location ~* "^/([0-9a-z-]{1,4})$" {
        limit_req zone=redirect_burst burst=10 nodelay;
        limit_except GET { deny all; }
        content_by_lua_block {
            package.path = "/www/wwwroot/{你的域名}/backend/lua/?.lua;;;" .. package.path
            local redirect = require "shorturl.redirect"
            redirect.go()
        }
    }
    
  # ══════════════════════[END]═════════════════════════════

插入示例：

server {
    listen 443 ssl;
    listen 443 quic;
    listen [::]:443 ssl;
    listen [::]:443 quic;
    server_name {你的域名};
    ...前面保持不变...

    ...在中间任意位置插入...
    
    ...后面保持不变...
}

五、生成 API Key

docker exec {PHP容器名} php /www/wwwroot/{你的域名}/nurl -new

预期输出如下：

正在生成密钥...

━━━ 常驻密钥 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  su_#  //Key 内容已隐去，下同
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
有效期：7 天。过期时间：2026-05-27T12:36:48+08:00

━━━ 一次性密钥（新增 20 个）━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  1. su_#1
  2. su_#2
  3. su_#3
  4. su_#4
  5. su_#5
  ……
  20. su_#20
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
请立即保存所有密钥，之后将不再显示。
每个密钥仅可使用一次。使用后会自动生成新密钥。
密钥永不过期，直到被使用。

密钥已存储至：/www/wwwroot/{你的域名}/backend/data/keys.json

━━━ 内部通信令牌（LPA-Key）━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  5b7b8a45d3e0db1685...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
已写入：/www/wwwroot/{你的域名}/backend/data/internal_token
此令牌用于 PHP↔Lua 内部通信认证，无需手动复制。

内部通信令牌（LPA-Key）由 nurl -new 首次执行时自动生成，用于 PHP↔Lua 内部 API 认证。无需手动操作。

Key 明文仅在此时显示一次，立即保存。

六、设置文件权限

cd {1panel安装路径}/www/wwwroot/{你的域名}

chmod 777 backend/data

chmod 666 backend/data/*

必须设置，否则 Lua 无法加载配置！

七、验证

curl -I https://{你的域名}

HTTP/2 200

curl https://{你的域名}/api/stat \ -H "X-Token: {su_你的Key}"

{"perm_count":0,"temp_count":0,"perm_limit":9999,"temp_limit":9999}

curl -X POST https://{你的域名}/api/create \
-H "Content-Type: application/json" \
-d '{"url":"https://{测试长链接}","key":"{su_你的Key}"}'

{"short_url":"https:\/\/{你的域名}\/{4位短码}"}

curl -I https://{你的域名}/{4位短码}

HTTP/2 302

声明

作者：圣堂之魂；发布于：2026-05-19；许可协议：CC BY-NC-SA 4.0

宝塔面板部署

声明

本页目录