Linux 部署

提供 Linux AMD64 和 Linux ARM64 完整包。先执行 uname -m，按服务器架构选择：

uname -m 输出	安装包文件名后缀
x86_64	linux-amd64.tar.gz
aarch64 或 arm64	linux-arm64.tar.gz

下载与校验

从 GitHub 最新正式版下载上表对应架构的完整包，以及 SHA256SUMS.txt。在下载目录打开 Bash，输入实际包路径：

read -r -p 'Linux 安装包完整路径：' package_path
sha256sum -- "$package_path"

将输出与 SHA256SUMS.txt 中该文件名对应的 SHA-256 比较，一致后继续。后续命令在同一个 Bash 会话中执行，系统需提供 tar。

创建独立运行目录

以下示例使用专用用户和全新的 /opt/mengka-nt 目录。同名用户或目录已存在时，先检查用途，不覆盖旧实例。

sudo useradd --system --home /opt/mengka-nt --shell /usr/sbin/nologin mengka
sudo mkdir /opt/mengka-nt
sudo tar -xzf "$package_path" -C /opt/mengka-nt
sudo chmod +x /opt/mengka-nt/mengka
sudo chown -R mengka:mengka /opt/mengka-nt

包内没有额外顶层文件夹；目录直接包含 mengka、public、data。运行用户必须能写入安装目录与 data，后续受控更新也需要该权限。

包内已提供 data/config.yaml，默认端口为 7878。按上述示例解压后，需要改端口时，在首次启动前编辑 /opt/mengka-nt/data/config.yaml 中的 server.port，例如：

server:
  port: 8787

确保运行用户 mengka 能读写此文件。已有配置文件时只修改 server.port，不要覆盖其他配置。然后进入程序目录，启动一次以完成初始化：

cd /opt/mengka-nt
sudo -u mengka ./mengka

保持终端打开，等待初始化地址。后续使用同一工作目录启动，不要从其他目录直接执行程序的绝对路径。

远程打开初始化页

完整初始化地址由终端显示，也保存在 /opt/mengka-nt/data/platform-auth/setup-access.txt。请完整复制地址，保留路径与 # 后的内容。

在本地电脑另开终端建立 SSH 转发。以下以自定义的 8787 为例；未修改配置时使用 7878，以服务器当前初始化地址为准：

ssh -N -L 8787:127.0.0.1:8787 你的SSH用户@服务器地址

SSH 不是 22 端口时加上 -p 实际SSH端口。本地端口可另选空闲端口，但目标端口须与服务器一致。

在本地浏览器打开初始化文件中的完整地址。如本地端口不同，只替换主机与端口，保留后面的路径与 # 后的全部内容。依次输入注册卡、确认协议、设置本地管理员与监听端口。

一张注册卡注册一个实例，默认永久 Free；保留原 data 后重启或更新无需再次用卡。完成后先用管理员登录确认，再在首次运行终端按 Ctrl+C 停止进程。

使用 systemd 后台运行

创建 /etc/systemd/system/mengka-nt.service：

[Unit]
Description=Mengka NT
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=mengka
Group=mengka
WorkingDirectory=/opt/mengka-nt
ExecStart=/opt/mengka-nt/mengka
Restart=on-failure
RestartSec=5
TimeoutStopSec=120
NoNewPrivileges=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target

确保工作目录与程序目录一致，且运行用户拥有写入权限。随后执行：

sudo systemctl daemon-reload
sudo systemctl enable --now mengka-nt
sudo systemctl status mengka-nt --no-pager
sudo journalctl -u mengka-nt -n 100 --no-pager

管理地址以此时日志和初始化时选择的端口为准。可继续使用 SSH 转发；配置 HTTPS 反向代理时应转发实际管理端口并支持 WebSocket。初始化时若再次修改了端口，也要同步修改端口转发和代理配置。

添加账号与插件服务

创建设备指纹，再添加 QQ 并选择协议。框架所在的 Linux 系统与账号选择的 QQ 协议相互独立，登录时按页面提示完成验证。

在插件页面导入适配当前框架的 IPC 插件，或创建 HTTP、正向／反向 WebSocket 服务连接外部插件。服务令牌保存在插件的受保护配置中，接入方式见插件开发。

数据与后续维护

优先使用框架顶部“在线更新”检查可用版本，按提示完成更新。更新期间等待服务恢复，长期没有响应时查看服务日志。

手动更新前执行 sudo systemctl stop mengka-nt，备份完整安装目录，将新包解压到临时目录，再替换原实例的 mengka、public、data/init.sql 和 data/migrations.sql。保留其余 data 内容，确认程序可执行且运行用户有读写权限，再执行 sudo systemctl start mengka-nt。

保持原工作目录，不让两份程序同时写入同一份数据。包内也提供 install-mengka-service.sh 服务注册脚本；已使用上述自建服务时，无需另行注册第二个服务。

启动失败时先查 journalctl，检查架构、工作目录、目录归属和端口。不要通过清空 data 解决启动问题。