宝塔部署教程

本教程适用于收到 Linux 版本交付包后，在服务器上使用宝塔面板自行部署。按照下列顺序完成配置，即可通过浏览器访问系统并完成授权。

一、部署前准备

请准备以下资料和环境：

下文统一使用以下示例，请根据实际情况替换：

本文使用已经编译好的交付包。前端页面随主程序一起提供，不需要另建前端站点，也不需要在服务器上运行前端构建命令。

二、上传安装包

1. 登录宝塔，打开「文件」。
2. 创建目录 /www/wwwroot/dav。
3. 将 Linux 安装包上传到该目录并解压。
4. 检查解压后的目录层级，确保主程序直接位于 /www/wwwroot/dav/dav.exe，避免多套一层文件夹。

目录示例：

/www/wwwroot/dav/
├── dav.exe                主程序，必须存在
├── toolbox.exe            运维工具，部分交付包提供
├── configs/
│   ├── app.ini            配置文件，必须存在
│   └── License            授权导入成功后生成，也可由供应商提供
├── public/                上传文件等持久化文件
└── runtime/               运行日志等文件

dav.exe 虽然以 .exe 结尾，但必须使用供应商提供的 Linux 版本，不能上传 Windows 版本代替。首次安装没有 License 文件时，可以先启动并登录，再按本文第八节申请授权。

在宝塔「终端」或 SSH 中执行以下命令，创建运行目录并设置权限：

cd /www/wwwroot/dav
mkdir -p configs public runtime
chmod 755 dav.exe configs public runtime
chmod 600 configs/app.ini

如果交付包只有 example.app.ini，先在 configs 目录中复制一份并命名为 app.ini，再设置权限和修改配置。

三、创建 MySQL 数据库

1. 打开宝塔「数据库」→「MySQL」→「添加数据库」。
2. 数据库名称填写 dav，字符集选择 utf8mb4。
3. 创建数据库用户，例如 dav_user，设置独立的强密码。
4. 本机数据库的访问权限选择「本地服务器」。
5. 保存数据库名称、用户名、密码和实际端口，下一步需要填写。

数据库用户需拥有该数据库内的建表、修改表及数据读写权限，以便程序首次启动时初始化表结构，后续升级时更新表结构。

**全新安装：**创建空数据库即可，程序会在启动时执行内置的数据库初始化脚本，不需要手工导入源码目录中的 SQL。

**迁移已有系统：**先恢复供应商或原系统提供的数据库备份及对应文件，再启动程序。不要将旧数据库备份导入已有数据的正式库。

四、修改程序配置

在宝塔「文件」中编辑：

/www/wwwroot/dav/configs/app.ini

本教程采用「程序监听本机端口，Nginx 提供域名访问」的方式，可按以下示例配置：

AppDebug = false
AppIp = 127.0.0.1
AppPort = 7001
AppJwtSecret = 请替换为本服务器独立生成的随机字符串
AppName = dav

DatabaseAutoCreate = false
DatabaseType = mysql
DatabaseDsn = "dav_user:请替换为实际数据库密码@tcp(127.0.0.1:3306)/dav?charset=utf8mb4&parseTime=true&loc=Local&multiStatements=true"

**保存前必须替换 AppJwtSecret 和数据库连接中的密码。**如果数据库名称、用户或端口与示例不同，也要一并替换。

可以在终端执行以下命令生成随机值，将输出的整行字符串填入 AppJwtSecret：

openssl rand -hex 32

配置说明：

注意事项：

• 示例中的 127.0.0.1:3306 表示数据库与程序在同一台服务器。使用远程数据库时，改为实际地址和端口，并配置对应的数据库访问权限。
• 密码包含英文双引号等字符时，要正确处理 INI 配置中的引号；初次部署可以使用由大小写字母和数字组成的足够长的随机密码，减少配置转义问题。
• 配置文件按程序工作目录下的 configs/app.ini 读取，不能改成 config/app.ini。
• 修改配置后，需要在宝塔中重启 Go 项目才会生效。

可选：使用 SQLite

若交付说明明确支持 SQLite，且无需安装 MySQL，可以跳过第三节，并将上例中的数据库配置部分替换为：

DatabaseAutoCreate = false
DatabaseType = sqlite3
DatabaseDsn = "file:configs/main.db?cache=shared&columnsWithAlias=true"

首次启动会在 configs 下创建 main.db。SQLite 支持取决于交付程序的编译方式；出现 requires cgo 等提示时，应联系供应商获取支持 SQLite 的交付包，或在全新安装时选用 MySQL。

已有数据的系统切换数据库类型前，需要另行迁移数据。仅修改配置不会自动将数据从一种数据库转入另一种数据库。

五、在宝塔中创建 Go 项目

在宝塔中打开「网站」→「Go 项目」→「添加 Go 项目」。不同版本的面板按钮名称可能略有差异，按以下字段填写即可。

这里的运行用户 root 是 Linux 系统用户，与后续网页登录账号是两回事。后续生成机器码、导入授权和日常启动时，应保持相同的运行用户。

如果宝塔提示需要安装 Go 项目管理组件，按面板提示安装后再添加项目。已编译的程序不需要使用 go run 启动。

保存后启动项目，并打开项目的「日志」页面，检查：

• 监听地址为 127.0.0.1:7001。
• 数据库连接成功，可看到类似 mysql successfully connected 的信息。
• 首次初始化没有 SQL 执行失败、数据库权限不足或迁移失败的错误。

首次初始化成功后，再次启动可能出现 no change，表示没有待执行的数据库迁移；如果同时存在其他报错，应继续排查。

在服务器终端执行以下命令检查本机服务：

curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:7001/

正常应输出 200，再配置域名。如果连接失败，先查看 Go 项目日志；如果响应为 500，先处理程序错误。

**只有进程启动还不代表部署完成。**还需要完成域名访问、登录和授权验证。

六、绑定域名并配置反向代理

1. 检查域名解析与端口

将 bi.example.com 解析到服务器 IP，并确认宝塔防火墙和云服务器安全组允许访问 80、443 端口。

本教程中的 7001 仅供本机 Nginx 访问，MySQL 的 3306 也不需要对公网开放。SSH 和宝塔管理端口按实际管理需要配置。

2. 绑定域名

打开 Go 项目的「设置」→「域名管理」，添加 bi.example.com。如面板提供「外网映射」开关，请开启，由 Nginx 将域名请求转发到 Go 程序。

如果面板没有自动生成反向代理站点，可以创建一个绑定该域名的纯静态站点，再在站点的「反向代理」中添加规则：

同一个域名使用一份站点配置即可；Go 项目已自动创建站点时，直接修改该站点，不要重复创建。

3. 检查代理配置

系统页面、静态资源、接口和 WebSocket 均由 Go 程序提供。请确认站点把请求转发到程序，不要将程序目录直接作为静态下载目录。

如果需要手工配置，在宝塔中打开该站点对应的 Nginx 配置，将现有的 location / 代理规则调整为下例，并补充 location /ws_api/。已有同名规则时替换原规则，不要重复追加。

以下配置放在该站点的 server { ... } 内，不是完整的 Nginx 配置文件；保留面板管理的域名、证书和证书验证配置。

# 上传大小示例，可按实际文件大小调整
client_max_body_size 100m;

location / {
    proxy_pass http://127.0.0.1:7001;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_cache off;
    proxy_read_timeout 300s;
}

location /ws_api/ {
    proxy_pass http://127.0.0.1:7001;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_cache off;
    proxy_buffering off;
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
}

同时检查宝塔默认生成的图片、JS、CSS 等静态资源 location 规则。如果这些规则直接从磁盘读取文件，会拦截本应由 Go 程序返回的资源，应移除或调整这些规则，让资源请求也转发到 127.0.0.1:7001。不要只代理接口路径。

保存配置，确认宝塔的 Nginx 配置检查通过，再重载 Nginx。打开：

http://bi.example.com

应能正常显示登录页。

七、配置 HTTPS 并首次登录

1. 配置 HTTPS

1. 打开域名对应站点的「SSL」设置。
2. 申请适用于该域名的证书，或上传已有证书及私钥。
3. 部署证书后，访问 https://bi.example.com，确认浏览器没有证书错误。
4. 确认 HTTPS 正常后，开启「强制 HTTPS」。

内网域名可使用单位内部证书，并确保访问电脑信任该证书。仅使用 IP 地址访问时，应根据实际证书的适用范围配置。

2. 首次登录

对于使用空数据库、由标准初始化脚本创建账号的全新安装：

如交付说明提供了独立账号密码，以交付说明为准。迁移已有数据库时，使用原账号密码，程序不会重置已有账号。

登录成功后，立即进入「系统设置」→「修改密码」，修改初始密码，并退出后使用新密码重新登录。

八、完成系统授权

授权操作在 最终部署并长期运行的服务器 上进行。先完成程序启动和管理员登录，再申请授权。

1. 获取机器码

1. 使用系统超级管理员账号登录，标准初始账号为 root。
2. 打开「系统设置」→「系统授权」。
3. 点击「点击查看机器码」。
4. 复制弹窗中的完整机器码，发送给软件供应商，并提供授权主体和交付联系信息。

如果菜单未显示，请确认使用的是超级管理员账号。也可以登录后直接访问：

https://bi.example.com/license

2. 获取授权码

供应商根据该服务器的机器码生成授权码并交付给您。请在同一台服务器、同一套运行环境中完成后续导入。

3. 导入授权

1. 在「系统授权」页面点击「导入/更新授权」。
2. 将供应商提供的完整授权码粘贴到输入框中。
3. 点击「确定」，等待系统提示导入成功。
4. 退出当前账号，再重新登录，使当前用户信息和授权状态更新。
5. 返回「系统授权」页面，确认当前状态与购买版本一致，产品名称和授权主体正确。

授权导入成功后，程序会将授权内容保存为：

/www/wwwroot/dav/configs/License

文件名为 License，Linux 下区分大小写，没有 .txt 后缀。该文件需要纳入备份并妥善保管。

4. 供应商直接提供授权文件时

若收到的是授权文件而非需要粘贴的授权码：

1. 如已有授权文件，先备份原文件。
2. 将供应商提供的文件上传到 /www/wwwroot/dav/configs/License。
3. 在本教程使用的 root 运行方式下，可执行以下命令限制文件权限：

chmod 600 /www/wwwroot/dav/configs/License

4. 在宝塔中重启 Go 项目，再退出并重新登录系统。
5. 打开「系统授权」确认授权状态。

5. 授权与服务器迁移

授权可能绑定主板、磁盘或设备 UUID，具体以签发内容为准。更换服务器、重建云主机、更换磁盘或改变虚拟化环境后，原授权可能失效。迁移前先联系供应商，在新服务器获取机器码并办理授权更新。

仅复制 License 文件不能保证在另一台机器上生效。授权到期后，联系供应商获取新授权，并通过「导入/更新授权」重新导入。

九、部署完成检查

以下项目全部通过后，再交付日常使用：

• [ ] 宝塔 Go 项目处于运行状态，已开启开机启动。
• [ ] 数据库连接及初始化成功，日志中没有数据库迁移失败信息。
• [ ] 通过正式域名可以打开登录页，刷新页面正常，静态资源没有 404。
• [ ] HTTPS 证书有效，强制 HTTPS 配置正常。
• [ ] 管理员能够登录，初始密码已修改。
• [ ] 配置示例中的密码和随机值占位文字已替换为实际值。
• [ ] 授权已导入，重新登录后显示正确的授权状态和主体。
• [ ] 文件上传正常，没有权限错误；超出限制时同步检查代理和程序端限制。
• [ ] 使用浏览器开发者工具检查实际使用的 WebSocket 请求，确认能够连接，无持续重连或代理错误。
• [ ] 在宝塔中重启一次 Go 项目后，仍能访问、登录，授权状态正常。
• [ ] 数据库、配置文件、授权文件及上传文件已完成首次备份。

十、备份与后续更新

在宝塔「计划任务」中设置数据库和文件备份。建议至少每日备份，并保留一份服务器外的副本。

使用 SQLite 时，数据库位于 configs/main.db。应先停止 Go 项目，再备份数据库及同目录可能存在的 main.db-wal、main.db-shm 文件，备份完成后启动项目。

更新程序前，先停止 Go 项目并备份数据库和文件，再按供应商提供的更新说明替换程序。保留原来的 configs/app.ini、configs/License 和 public/，不要用新包中的示例配置覆盖正式配置。

更新后启动程序，重新检查数据库迁移、页面访问、登录和授权。若更新失败且已执行数据库变更，应按同一备份时间点恢复数据库、程序和文件，不能仅替换回旧程序。

十一、常见问题

需要协助时，请提供报错时间、脱敏后的截图、程序日志、交付版本及服务器系统／CPU 架构。数据库密码、密钥和完整授权文件通过约定的安全方式单独传递。

参考资料

宝塔界面会随版本调整，可结合以下官方资料核对操作：

• 宝塔面板：Go 项目管理字段说明
• 宝塔面板：反向代理配置指南
• 宝塔面板：添加 MySQL 数据库
• Nginx：WebSocket 代理配置