4.3 宝塔面板安装教程

2 months ago
eeeffa0

宝塔面板安装教程

首次使用的关键配置：木雷短网址使用应用实际收到的 Host + 短码 精确匹配记录。后台域名为 s.example.com 时，宝塔传给应用的 Host 也必须是 s.example.com。Host 被改成内部地址、容器名、回源域名或错误端口时，后台和 /health 可能正常，但公开短链接会返回 404。

保留说明：本文保留原文章 335 及 ymmi.cn 原教程的授权来源，并按木雷短网址 v2.22.3 的实际安装向导与当前安全基线重新校对。宝塔菜单名称可能随版本变化，实际界面以当前面板为准。

宝塔面板可以完成 Docker 应用安装、域名绑定、HTTPS、反向代理、日志查看和备份。若要使用宝塔的 Docker 应用商店，应先将面板升级到支持该功能的版本；找不到“木雷短网址”应用时，可以使用本页的容器编排方式部署。

1. 安装前准备

开始前确认：

  • 已安装宝塔面板及 Docker 管理功能。
  • 域名的 A/AAAA 记录已经指向服务器。
  • 公网只需放行 Web 入口 80、443 和必要的宝塔管理端口。
  • 已确定配置、数据和日志的持久化目录；本文示例使用 /www/docker/dwz。
  • 生产环境升级或重装前，已经备份数据库、config/ 和 data/。

根据规模选择存储组合：

场景 数据库 缓存 发号器 说明
单机或个人使用 SQLite memory local 最简单，不需要预装 MySQL 或 Redis
单实例生产 MySQL/PostgreSQL Redis local 或 Redis 数据库和 Redis 仅在私网可达
多实例生产 MySQL/PostgreSQL Redis Redis 所有实例共享数据库、Redis 与 JWT_SECRET

多实例不要使用 local 发号器，否则不同进程无法协调计数。

2. 通过 Docker 应用商店安装

  1. 登录宝塔，打开 Docker → 应用商店。
  2. 搜索“木雷短网址”。找到应用后选择 安装。
  3. 设置应用名称、镜像版本、持久化目录和主机端口。生产环境应固定经过验证的镜像版本，并记录本次安装版本。
  4. 将应用端口映射到主机 8080。若面板支持绑定监听地址，使用 127.0.0.1:8080，让公网流量只经过反向代理。
  5. 若安装窗口支持域名绑定，可直接填写准备好的域名；否则按第 4 节手动创建站点和反向代理。
  6. 等待容器进入运行状态，在 已安装 或 容器 页面检查日志。

启动初期短暂出现 502，通常表示镜像仍在拉取或服务尚未就绪。容器持续重启时不要反复重装，应先查看日志。

如果应用商店没有对应条目，继续使用下面的容器编排方式，功能与运行镜像相同。

3. 使用容器编排安装

在宝塔中打开 Docker → 容器编排 → 添加容器编排，项目目录填写 /www/docker/dwz，使用以下单机配置：

services:
  dwz-server:
    image: docker.cnb.cool/mliev/dwz/dwz-server:latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      TZ: Asia/Shanghai
      HTTP_ADDR: ":8080"
    volumes:
      - /www/docker/dwz/config:/app/config
      - /www/docker/dwz/data:/app/data
      - /www/docker/dwz/logs:/app/logs

创建编排前可以在宝塔终端中准备目录：

mkdir -p /www/docker/dwz/config /www/docker/dwz/data /www/docker/dwz/logs

保存并启动后检查：

docker compose -f /www/docker/dwz/compose.yaml ps
curl --fail http://127.0.0.1:8080/health/simple

宝塔保存 Compose 文件的实际名称可能不同；命令中的路径应以面板显示的项目文件为准。完整的 MySQL、Redis 编排示例见 Docker 部署。

4. 绑定域名、HTTPS 与反向代理

  1. 在 网站 中创建与短链域名相同的站点。
  2. 在站点的 SSL 页面申请或导入证书，并启用 HTTPS。
  3. 打开 反向代理 → 添加反向代理。
  4. 代理目录填写 /，目标 URL 填写 http://127.0.0.1:8080，关闭缓存和内容替换。
  5. 标准 80/443 入口的“发送域名”填写 $host；公开 URL 确实使用 :8443 等非标准端口时填写 $http_host 以保留端口。若面板只接受固定值，填写当前公开短域名，绝不能填写上游地址 127.0.0.1:8080。

Nginx 代理配置至少应包含：

proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;

非标准公网端口才使用：

proxy_set_header Host $http_host;

关键链路如下：

https://s.example.com/abc123
        │ DNS、证书
        ▼
宝塔 Nginx ── Host: s.example.com ──> dwz-server
                                             │ 精确匹配
                                             ▼
                              domains.domain + short_code

应用应部署在域名根路径，不要放在 /dwz/ 等子路径下；若入口前还有 CDN，应让 CDN 和宝塔都保留公开短域名，并按 CDN 官方地址范围配置 Nginx real_ip 信任来源。

Q：为什么 Host 决定短链接能否被找到？

程序收到 GET /abc123 后会读取 HTTP Host，再查询同一域名下的 abc123。s.example.com、www.s.example.com、s.example.com:8443 和 127.0.0.1:8080 都是不同的查找值。安装时使用的 IP 或管理域名不会自动注册为公开短域名。

Q：宝塔“发送域名”应该填写什么？

  • 公开地址为标准 HTTP/HTTPS：使用 $host，后台填写 s.example.com。
  • 公开地址明确带非标准端口：使用 $http_host，后台填写相同的 s.example.com:8443。
  • 面板只接受固定值：填写公开短域名，不要填写代理目标、容器名或内部端口。

Q：$host 和 $http_host 有什么区别？

$host 适合标准 80/443，可以避免把显式的默认端口意外传给应用；$http_host 保留客户端 Host 头中的端口，适合公开 URL 必须携带非标准端口的场景。选择哪一个不重要，最终传给应用的 Host 与后台域名记录完全一致才是关键。

Q：只设置 X-Forwarded-Host 可以吗？

不可以。v2.22.3 的短链查找读取真正的 HTTP Host，不会用 X-Forwarded-Host 替代。必须设置 proxy_set_header Host ...。

Q：为什么后台和 /health 正常，短网址仍是 404？

后台静态资源和健康接口不使用短域名查找记录，因此不能证明 Host 正确。依次检查宝塔“发送域名”、Nginx 的 Host 配置、后台域名是否包含错误的 :443、短码是否存在，以及应用是否部署在根路径。

Q：HTTPS 应配置在哪里？后台选择 https 会自动签发证书吗？

证书和 HTTP 到 HTTPS 跳转由宝塔/Nginx/CDN 等公网入口负责。后台协议选择 https 只决定新建短链的完整 URL，不会申请证书或修改代理；代理仍应传递 X-Forwarded-Proto $scheme。修改域名协议也不会批量改写已经创建的短链。

Q：使用 CDN 或多个短域名时怎么办？

CDN 回源必须保留访客访问的公开短域名，不能统一改成源站域名。每个公开短域名都应分别完成 DNS、证书、站点/代理和后台域名配置；裸域与 www 域名需要分别添加，或在入口明确做规范化跳转。

Q：如何快速判断故障在哪一层？

  • DNS 或证书错误：请求尚未正确到达宝塔入口。
  • 502：宝塔无法连接应用端口。
  • 404：优先检查 Host、端口和短码是否精确匹配。
  • 403：短链禁用，或被访问/安全策略阻止。
  • 410：短链已过期。
  • 301、302、307、308 且包含正确 Location：跳转链路正常。

5. 完成首次安装向导

通过绑定的 HTTPS 域名访问服务。未安装时会自动进入向导。

5.1 接受许可协议

阅读许可协议，确认同意后进入下一步。

接受软件许可协议

5.2 配置数据库、缓存与发号器

单机安装可以直接选择：

  • 数据库：SQLite，文件路径 ./config/sqlite.db。
  • 缓存驱动：memory。
  • 发号器驱动：local。

选择 MySQL、PostgreSQL 或 Redis 时，容器中的 localhost 指容器自身，应填写同一私有 Docker 网络内的服务名或私网地址。填写完成后先执行“测试连接”。

配置数据库、缓存与发号器

5.3 创建管理员

填写管理员用户名和强密码。当前安装流程不会创建可跳过的 admin/admin 默认账号。

创建系统管理员

5.4 确认安装

核对数据库、缓存、发号器和管理员摘要，选择“开始安装”。系统会执行迁移、创建管理员并写入 config/install.lock。

确认安装配置

6. 首次登录与域名检查

安装完成后不要立即创建正式业务短链。安装流程只初始化存储和管理员，不会自动创建公开短域名。按以下顺序完成首次使用：

  1. 使用刚创建的管理员登录后台。
  2. 打开 链接管理 → 域名，添加外部访问使用的域名。
  3. 域名字段只填写 Host，例如 s.example.com，不要包含协议、路径或 Query。
  4. 协议选择外部实际使用的 https，保存后创建一条测试短链。
  5. 分别访问 /health/simple、/health，确认 HTTP、数据库和 Redis 状态正常。

域名和协议会复制到新建短链，后续修改域名记录不会自动迁移已有短链。因此应先完成 DNS、证书和反向代理，再创建第一条正式短链。

将变量替换为测试域名和真实短码，在宝塔服务器上验收：

DWZ_SHORT_HOST=s.example.com
DWZ_SHORT_CODE=abc123

# 直连应用：验证 Host + 短码能否在程序内命中
curl -sS -o /dev/null -D - \
  -H "Host: ${DWZ_SHORT_HOST}" \
  "http://127.0.0.1:8080/${DWZ_SHORT_CODE}"

# 公开入口：同时验证 DNS、证书和反向代理
curl -sS -o /dev/null -D - \
  "https://${DWZ_SHORT_HOST}/${DWZ_SHORT_CODE}"

两个请求都应返回 301、302、307 或 308。第一条成功而第二条失败，通常是 DNS、证书、宝塔或 CDN 的 Host 传递问题；两条都返回 404，则检查后台域名与测试短码。不要使用 curl -I，当前短码入口处理的是 GET 请求。

7. MySQL 与 Redis 的安全连接

不要照搬旧教程中开放公网数据库端口的做法：

端口 公网放行 正确做法
80、443 是 由宝塔站点和 HTTPS 入口处理
应用 8080 否 绑定回环地址或仅在反向代理网络开放
MySQL 3306 否 只允许应用所在私有网络访问
Redis 6379 否 私网访问、设置强密码，不映射到公网

推荐让应用、MySQL 和 Redis 位于同一个 Compose 私有网络，并通过服务名通信。若必须连接宝塔宿主机中已有的 MySQL 或 Redis，可以用下面的命令查看容器网络网关，但不要硬编码旧教程中的 172.18.0.1：

docker network inspect baota_net --format '{{(index .IPAM.Config 0).Gateway}}'

网络名称和网关以当前服务器为准。数据库访问控制与主机防火墙只允许实际 Docker 私网来源；不要把 Redis 设置为无边界的 0.0.0.0 后再向公网开放 6379。

8. 升级与备份

应用商店安装的实例可在 Docker → 应用商店 → 已安装 中查看更新；容器编排方式可在备份后重新拉取镜像并重建：

docker compose pull
docker compose up -d
docker compose logs --tail=200 dwz-server
curl --fail http://127.0.0.1:8080/health

升级前至少备份：

  • MySQL/PostgreSQL 数据库，或停机后的 SQLite 文件。
  • /www/docker/dwz/config，包括 config.yaml 和 install.lock。
  • /www/docker/dwz/data 中的上传文件。
  • Compose 配置及受控保存的密钥。

9. 常见问题

安装后持续显示 502

在宝塔容器页面查看启动日志，确认端口映射、目录权限和镜像拉取状态。健康检查不通过时，先解决服务启动错误。

后台正常，但短网址返回 404

按第 4 节 Q/A 和第 6 节双入口命令检查。标准 80/443 使用 $host；只有公开 URL 带非标准端口时使用 $http_host，并确保后台域名包含相同端口。

重启后再次进入安装向导

说明 /app/config 没有正确持久化，或 install.lock 丢失。恢复挂载与备份，不要直接重复初始化已有数据库。

数据库或 Redis 测试连接失败

不要填写容器自身的 localhost。检查服务名、私有网络、账号密码和最小访问权限；不要用开放公网端口作为解决办法。

相关说明：首次安装、Docker 部署、数据库与迁移、缓存、Redis 与 ID 发号器。宝塔界面操作可参考其官方的 Docker 应用商店 与 反向代理 文档。