在 Linux 上自托管 Mqttable Web

这里介绍的是 Mqttable Web 服务端，不是 Linux 桌面版。只有经过校验的稳定版 manifest 发布后，安装包才算正式提供下载。目前候选支持系统为 Debian 12、Ubuntu 24.04（amd64 DEB）和 Rocky Linux 9（x86_64 RPM）；不承诺 ARM64 或其他 Linux 发行版。

这是单个 Owner 专用的私有工作台，不是托管多用户服务。Owner 可使用与桌面版相同的 Free 能力；只有现有 Pro 功能需要有效的 Pro 权益。登录、Owner 绑定和 Pro 激活依赖可访问的 mqttable.com 授权服务；对应 instance API 未就绪前，不要对外开放生产实例。

选择并校验安装包

下载页 提供 Web 安装包后，按系统选择 DEB 或 RPM，安装前核对公布的 SHA-256。页面提供的可复制命令会通过 HTTPS 下载、用 sha256sum -c - 校验，然后才调用系统包管理器。如果 Web 区域显示不可用或尚未发布，不要猜测下载地址，也不要用桌面版安装包代替。

安装软件包

对已校验的本地文件运行 sudo apt install ./mqttable-web.deb 或 sudo dnf install ./mqttable-web.rpm。安装过程会创建专用 mqttable-web 用户、非秘密配置 /etc/mqttable-web/mqttable-web.env、仅 root 可读的 /etc/mqttable-web/secrets.env 和数据目录 /var/lib/mqttable-web。安装不会自动启动或启用服务。保护生成的秘密和数据目录，不要把秘密写入普通配置文件。安装包不包含可复用的 RPC cookie；实例首次启动时会在私有数据目录生成自己的 cookie，并在重启后复用。

配置 HTTPS

管理员编辑 /etc/mqttable-web/mqttable-web.env，将 PHX_HOST 设为唯一的公网 DNS 主机名，并选择一种 MQTTABLE_WEB_TLS_MODE：

• acme（包默认值）：直接在 PORT=443 提供 HTTPS，公网 80 用于 HTTP-01 挑战。自行填写 MQTTABLE_ACME_EMAIL，阅读 CA 条款后显式设置 MQTTABLE_ACME_ACCEPT_TERMS=true；安装器不会替你接受条款。MQTTABLE_ACME_ENV=staging 只用于测试，其证书不受普通浏览器信任。
• manual：使用自备的有效证书直接提供 HTTPS。填写绝对路径 MQTTABLE_TLS_CERTFILE 和 MQTTABLE_TLS_KEYFILE。证书须覆盖 PHX_HOST，服务账户须可读。若文件放在 /etc/mqttable-web，应设为 root:mqttable-web、权限 0640，特别注意保护私钥。更新证书由管理员负责。
• proxy：在同一主机上用管理员管理的 HTTPS 反向代理转发到仅监听 loopback 的 HTTP PORT=51883，设置 PHX_PORT=443，保留准确的外部 Host、HTTPS scheme 和 WebSocket 升级。不要公开内部 HTTP、本地 MCP（默认 127.0.0.1:51884）或 RPC（127.0.0.1:6789）监听器。

Docker 镜像另有部署方式：Web 仍使用 51883，由宿主机 HTTPS 反向代理接入。不要把原生包直连 443 的配置套到 Docker 示例中。

启动服务

检查配置和网络策略后，显式运行 sudo systemctl enable --now mqttable-web.service。查看 systemctl status mqttable-web.service；仅在证书可信时访问 https://<你的域名>/instance。软件包不会打开防火墙。不要绕过浏览器 TLS 安全检查来伪装 staging 证书可用。

绑定 Owner

在服务器上运行 sudo mqttable-web setup。短时有效的 setup code 只打印在终端。到实例的 /instance 页面输入该 code，完成 mqttable.com 账户确认，再显式绑定此账户为 Owner。仅访问页面不会认领实例。一个私有实例只允许一个已绑定 Owner；另一个 Pro 账户也不能进入。

Setup code 有效期为 15 分钟，再次签发会使旧 code 失效。网站确认开始后，该请求另有 10 分钟有效期；过期后需重新开始这一步，并回到原来的实例浏览器完成绑定。

诊断问题

运行 sudo systemctl status mqttable-web.service、sudo journalctl -u mqttable-web.service -n 100 --no-pager 和 sudo mqttable-web tls-status。最后一条只报告脱敏后的证书状态，不输出私钥。重试前检查 DNS、证书域名与有效期、80 端口挑战、443 端口、文件权限和外部 Host。公开 /mcp 会被拒绝，不要代理本地 MCP 监听器。

Pro 失效不会锁住 Owner 的 Web 访问。普通 MQTT 连接保留；定时消息、Replay、Bench 和代理 toxic schedule 会停止或暂停，需在当前额度内主动重启。实例状态损坏时会拒绝访问：请按产品私有 Web 文档执行显式运维恢复，不要通过删除状态或更换密钥来选择其他 Owner。

升级、备份与卸载

更换安装包前，安全备份完整的 /var/lib/mqttable-web 和 /etc/mqttable-web/secrets.env，并保留 /etc/mqttable-web/mqttable-web.env 及自备 TLS 证书和私钥。为获得一致副本，应先停止服务；恢复只由管理员显式执行到相同包版本，并保持属主和权限。浏览器内的数据导出不是完整服务器备份。不承诺自动降级或迁移。用系统包管理器安装已校验的新包，检查状态；若此前停止服务，则显式重启。卸载包会停止并禁用服务，但保留数据与秘密；只有明确要销毁实例时才另行清除。

ACME 前提与失败处理

HTTP-01 要求唯一的公网 DNS 名称解析到本机，且公网 TCP 80 在签发和续期时可达。公网 443（或显式选择的直连 HTTPS 端口）也须可供用户访问。本地私有 CA 测试不能证明公网 ACME 可用。CA 不可达或校验失败时，先看 journal 和 TLS 状态，修复 DNS、网络、条款或账户配置，再审慎重试，不要连续高频申请证书。Staging 证书链不受生产浏览器信任；只有完成获授权的发布验收后才使用 production。数据目录中的 ACME 账户和证书要一并备份，不要在日志或工单泄露账户密钥、证书私钥。