部署总览

从 GitHub 最新正式版下载完整安装包及 SHA256SUMS.txt。提供 Windows AMD64、Linux AMD64 与 Linux ARM64 完整包；按照运行框架的系统和处理器架构选择安装包。

完整包包含程序、网页资源和数据库初始化文件，不需要另装 Go、Node.js、数据库服务或媒体处理容器。解压后没有额外顶层文件夹，程序与 public、data 位于同一目录。

选择平台

• Windows 部署：解压启动，在浏览器完成注册卡激活和管理员设置。
• Linux 部署：使用独立运行目录，完成初始化后配置后台服务。

首次启动与激活

1. 校验安装包后，解压到新的独立目录。
2. 进入该目录启动程序，复制终端显示的完整初始化地址；地址也保存在 data/platform-auth/setup-access.txt。
3. 在浏览器打开完整地址，保留路径与 # 后的内容；依次验证注册卡、确认使用协议、设置管理员和监听端口。
4. 初始化完成后，用管理员账号登录框架首页，再添加 QQ 和插件。

Windows 首次在终端交互启动时会先询问网页访问端口，按 Enter 使用 7878，选择会保存到 data/config.yaml。已有配置时直接使用其中的端口，不会再次询问。Linux 包已附带 data/config.yaml，可在首次启动前修改。Windows 也可以将 data/config.example.yaml 在原 data 目录内改名为 config.yaml 后设置端口，例如：

server:
  port: 8787

示例改用 8787；请换成实际可用的端口。始终先进入程序所在目录再启动，配置路径相对于该工作目录。已有配置文件时只修改 server.port，不要覆盖其他配置。

远程服务器的 127.0.0.1 指服务器本机；可通过远程桌面或 SSH 端口转发打开初始化地址，操作方法见对应平台页面。初始化时若再次修改监听端口，之后的访问地址、反向代理和端口转发也应同步调整。

一张注册卡注册一个实例，默认永久 Free。原实例保留 data 后重启或更新无需再次用卡。管理员凭据和初始化地址请自行妥善保存。

管理端访问

管理端可使用 HTTP IP 地址与端口访问，也支持通过域名和 HTTPS 反向代理访问。代理应转发实际管理端口，保留 Host、原始访问协议与 WebSocket 升级头；公开访问建议配置 HTTPS。

添加账号与插件

登录后先创建设备指纹，再添加 QQ 并选择协议。框架运行系统与 QQ 登录协议相互独立。

托管 IPC 插件通过框架插件导入页面安装：选择适配当前框架与服务器架构的成品包，确认来源和权限，配置后启动，并检查“运行中 / IPC 已连接”状态。IPC 插件不需要填写 WebSocket 地址或服务令牌。

外部插件可通过 HTTP、正向或反向 WebSocket 服务连接。详见插件接入和通信协议。

更新与数据保留

可在框架顶部“在线更新”检查可用版本，按提示完成更新并等待服务恢复。手动更新前先停止框架并备份完整安装目录，再更新程序、public 与包内配套 SQL 文件，保留 data 中的数据库、配置、实例凭据和登录缓存。

以后始终从同一个工作目录启动，不要让两份程序同时写入同一份数据。更新后若出现初始化页，先核对启动目录与数据文件，再查看日志，不要直接重新注册或清空 data。