Ubuntu 24.04 安装 plugNmeet 2.5.3 指南

目标：在一台 Ubuntu 24.04 裸机服务器上完成 plugNmeet 2.5.3 的手动部署——源码编译出服务端二进制、部署官方客户端静态资源、安装 MariaDB 12.3 / Redis / NATS / LiveKit 依赖栈，并用 systemd 托管全部服务，实测验证登录页面与健康检查接口均正常响应。

一、环境信息

本文全部命令与回显在下列环境实测取得：

操作系统：Ubuntu 24.04 LTS（x86_64）
plugNmeet 服务端：v2.5.3（源码 tag，编译产物 78MB）
plugNmeet 客户端：官方 client.zip，内含版本 v2.5.4
Go：1.27.2　gcc：13.3.0　git：2.43.0
mupdf/mutool：1.28.5（源码编译）　FFmpeg：6.1.1（apt 自带）
MariaDB：12.3.3　Redis：8.10.2　NATS：2.15.1　LiveKit：1.13.11
部署目录：/opt/plugNmeet/（配置、客户端、日志、上传、录制、产物）
端口：8145（Web/API）、8146/8147（LiveKit）、50000-60000/UDP（RTC 媒体）、4222/8222（NATS）
数据库：本机 MariaDB，库名/账号 plugnmeet

🔗 组件定位、架构与选型对比见《plugNmeet 2.5.3 介绍与选型指南》。

二、前置条件

硬件：最低 2 核 4GB 内存、40GB 磁盘；如需开启录制或 AI 转写，建议 4 核 8GB 起步（编译阶段峰值内存消耗约 2GB）。
系统软件：具备 sudo 权限，能访问互联网（部分资源可能需要重试或走代理，见各步骤 ⚠️ 标注）。
端口规划：确认 8145、8146、8147 未被占用，UDP 50000-60000 防火墙放行；本机默认仅监听 127.0.0.1 的 3306/6379/4222 不对公网开放。
域名与 TLS：本文为内网手动部署路径，先用 HTTP 验证；公网生产部署建议前置 HAProxy/Nginx 做 TLS 终结（官方一键脚本即此思路，见选型指南篇 5.3 节）。

三、版本选型说明

plugNmeet 2.5.3 在 Ubuntu 24.04 上没有「开箱即用」的预构建安装包，版本选型时需明确三条路径的边界：

路径	说明	适用性
官方一键脚本	安装脚本会引入整套编排工具栈并强依赖公网域名与 80/443	有公网域名、接受其技术栈的服务器
源码编译（本文）	Go 编译服务端二进制 + 官方客户端资源包 + 自建 systemd	内网/无域名/需要完全掌控部署形态
等待官方二进制	v2.5.3 发布页未提供预构建二进制产物	截至 2026-10-26 不适用

为什么源码编译必须带三个「重依赖」，这是版本选型时要提前知道的：

CGO 与 Azure Speech SDK C 库：服务端 insights（AI 转写/摘要）模块链接了微软语音 SDK 的 C 动态库，编译时必须 CGO_ENABLED=1 并指定该库的头文件与链接路径（即使暂不使用 AI 功能，链接也是强制的）。
mupdf/mutool：白板 PDF 转页依赖 mutool 命令，官方构建环境内从源码编译安装 1.28.5 版本。
Go 1.27：v2.5.3 的 go.mod 声明 go 1.27.1，本文实测用 1.27.2（与官方运行时口径一致）。

依赖组件版本矩阵（全部官方渠道，2026-10-26 实查）：

组件	版本	官方来源
plugNmeet-server	2.5.3	github.com/mynaparrot/plugNmeet-server（tag v2.5.3）
plugNmeet 客户端	v2.5.4	mynaparrot/plugNmeet-client release 的 client.zip
LiveKit	1.13.11	github.com/livekit/livekit/releases
NATS	2.15.1	github.com/nats-io/nats-server/releases
MariaDB	12.3.3	官方 mariadb_repo_setup 脚本仓库
Redis	8.10.2	packages.redis.io 官方仓库

四、安装编译工具链

$ sudo apt-get update
$ sudo DEBIAN_FRONTEND=noninteractive apt-get install -y build-essential ca-certificates wget curl git make pkg-config unzip \
  libasound2-dev libopus-dev libopusfile-dev libssl-dev libsoxr-dev \
  libreoffice img2pdf ffmpeg fontconfig fonts-dejavu fonts-dejavu-extra fonts-noto fonts-noto-cjk \
  fonts-liberation fonts-liberation2 fonts-linuxlibertine fonts-sil-gentium fonts-sil-gentium-basic
Setting up libheif-plugin-aomdec:amd64 (1.17.6-1ubuntu4.9) ...
Setting up libheif-plugin-aomenc:amd64 (1.17.6-1ubuntu4.9) ...
Processing triggers for libc-bin (2.39-0ubuntu8.9) ...
$ gcc --version | head -1
gcc (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0
$ git --version
git version 2.43.0

说明：

libasound2-dev 等 -dev 包是链接微软语音 SDK 与音频栈所需的开发文件；
libreoffice、字体包、img2pdf、ffmpeg 是白板文档转换与录制链路的运行时依赖，来自官方构建环境的固定清单；
字体包中 fonts-noto-cjk 保证中文在白板导出 PDF 中不乱码。

五、方案一：源码编译服务端二进制

5.1 安装 Go 1.27.2

$ curl -s -L -o /tmp/go.tgz https://go.dev/dl/go1.27.2.linux-amd64.tar.gz
$ sudo tar -C /usr/local -xzf /tmp/go.tgz
$ sudo ln -sf /usr/local/go/bin/go /usr/local/bin/go
$ go version
go version go1.27.2 linux/amd64

⚠️ 实测提示：从 go.dev/dl 下载偶尔会出现「下载成功但文件不完整」（后续解压报错却不易察觉）。建议下载后 tar -tzf /tmp/go.tgz >/dev/null && echo OK 校验一次再解压。

5.2 安装 Azure Speech SDK 动态库（CGO 链接必需）

Ubuntu 24.04 的微软软件源中已不再收录 Speech SDK 的 deb 包，官方构建环境的做法是直接解压官方 Linux 二进制包到 /opt/speechsdk，本文照做：

$ export SPEECHSDK_ROOT=/opt/speechsdk
$ sudo mkdir -p "$SPEECHSDK_ROOT"
$ cd /tmp && wget -O SpeechSDK-Linux.tar.gz https://aka.ms/csspeech/linuxbinary
$ sudo tar --strip-components=1 -xzf SpeechSDK-Linux.tar.gz -C "$SPEECHSDK_ROOT"
$ rm SpeechSDK-Linux.tar.gz
$ ls "$SPEECHSDK_ROOT"
LICENSE.md  REDIST.txt  ThirdPartyNotices.md  include  lib
$ ls "$SPEECHSDK_ROOT/lib/x64" | head -5
libMicrosoft.CognitiveServices.Speech.core.so
libMicrosoft.CognitiveServices.Speech.extension.audio.sys.so
libMicrosoft.CognitiveServices.Speech.extension.codec.so
libMicrosoft.CognitiveServices.Speech.extension.kws.ort.so
libMicrosoft.CognitiveServices.Speech.extension.kws.so

把运行时搜索路径注册进动态链接器：

$ echo /opt/speechsdk/lib/x64 | sudo tee /etc/ld.so.conf.d/speechsdk.conf
$ sudo ldconfig

5.3 编译安装 mupdf/mutool（白板 PDF 转换）

$ cd /tmp
$ wget -O mupdf.tar.gz https://casper.mupdf.com/downloads/archive/mupdf-1.28.5-source.tar.gz
$ mkdir mupdf && tar --strip-components=1 -xzf mupdf.tar.gz -C mupdf && rm mupdf.tar.gz
$ cd mupdf
$ make -j$(nproc) HAVE_X11=no HAVE_GLUT=no HAVE_LEPTONICA=no HAVE_TESSERACT=no prefix=/usr/local install
$ mutool -v
mutool version 1.28.5

编译约 5-10 分钟，HAVE_X11/HAVE_GLUT/HAVE_LEPTONICA/HAVE_TESSERACT=no 与官方构建环境一致，只保留服务器端需要的功能。

⚠️ 下载实测：官方源 casper.mupdf.com 当时出现过一次下载中断（解压报 gzip: stdin: unexpected end of file，make 报 No rule to make target 'install'——其实是包没下完整），重试后完整下载（66MB），官方源可用。

5.4 获取源码并编译

$ sudo git clone --depth 1 --branch v2.5.3 https://github.com/mynaparrot/plugNmeet-server.git /usr/local/src/plugNmeet-server
Cloning into '/usr/local/src/plugNmeet-server'...
$ cd /usr/local/src/plugNmeet-server
$ git describe --tags
v2.5.3

按官方构建脚本的编译参数执行（依赖下载在国内网络环境建议走 goproxy.cn）：

$ export GOPROXY=https://goproxy.cn,direct
$ export SPEECHSDK_ROOT=/opt/speechsdk
$ go mod download
$ CGO_ENABLED=1 GOOS=linux GOARCH=amd64 GO111MODULE=on \
  CGO_CFLAGS="-I$SPEECHSDK_ROOT/include/c_api" \
  CGO_LDFLAGS="-L$SPEECHSDK_ROOT/lib/x64 -lMicrosoft.CognitiveServices.Speech.core" \
  go build -trimpath -ldflags '-w -s -buildid=' -a -o plugnmeet-server main.go
$ ls -lh plugnmeet-server
-rwxr-xr-x 1 root root 78M Oct 26 10:39 plugnmeet-server

编译成功时 go build 静默无输出，产物约 78MB。安装到系统路径：

$ sudo cp plugnmeet-server /usr/local/bin/plugnmeet-server && sudo chmod +x /usr/local/bin/plugnmeet-server

⚠️ 依赖下载实测：go mod download 全量拉取约 1GB 依赖，直连 proxy.golang.org 在内网实测 connection refused，改用 goproxy.cn 后正常，全程约 5 分钟。

六、方案二：部署客户端静态资源

服务端只提供 API 与页面壳，会议前端的 JS/CSS 打包在官方 client.zip 中，按版本发布。服务端启动后会从 client.path 指定目录渲染页面。

$ cd /tmp && wget -q -O client.zip \
  https://github.com/mynaparrot/plugNmeet-client/releases/latest/download/client.zip
$ ls -lh client.zip
$ sudo mkdir -p /opt/plugNmeet/client
$ sudo unzip -q client.zip -d /opt/plugNmeet/client

官方包内自带一层 client/ 目录，整理成服务端期望的布局：

$ cd /opt/plugNmeet
$ sudo mv client/client/dist client_dist_tmp && sudo rm -rf client && sudo mkdir client
$ sudo mv client_dist_tmp /opt/plugNmeet/client/dist
$ ls /opt/plugNmeet/client/dist
assets  index.html  login.html  version.txt
$ cat /opt/plugNmeet/client/dist/version.txt
v2.5.4

客户端版本（v2.5.4）略新于服务端（v2.5.3）属正常现象——客户端按独立节奏发布并保持向后兼容；如需与服务端严格同版，可在客户端 release 页按服务端版本时间选择最近的对应包。

七、安装依赖组件

7.1 MariaDB 12.3（历史数据）

用官方仓库脚本添加 MariaDB 源并安装 12.3 系列：

$ curl -LsS https://r.mariadb.com/downloads/mariadb_repo_setup | sudo bash -s -- --mariadb-server-version=12.3
$ sudo apt-get install -y mariadb-server
$ mariadb --version
mariadb from 12.3.3-MariaDB, client 15.2 for debian-linux-gnu (x86_64) using  EditLine wrapper

建库、建账号并导入官方初始表结构（install.sql 来自服务端源码仓库 sql_dump/）：

$ sudo mariadb -e "CREATE USER IF NOT EXISTS plugnmeet@localhost IDENTIFIED BY 'q1w2e3r4'; \
  CREATE DATABASE IF NOT EXISTS plugnmeet; \
  GRANT ALL PRIVILEGES ON plugnmeet.* TO plugnmeet@localhost; FLUSH PRIVILEGES;"
$ sudo mariadb plugnmeet < install.sql
$ mariadb -uplugnmeet -pq1w2e3r4 plugnmeet -e "SHOW TABLES;"
Tables_in_plugnmeet
pnm_recordings
pnm_room_analytics
pnm_room_artifacts
pnm_room_info

本文示例口令统一为 q1w2e3r4，生产环境请换成强口令。

7.2 Redis 8（实时状态）

$ curl -fsSL https://packages.redis.io/gpg | sudo gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg
$ echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb noble main" | sudo tee /etc/apt/sources.list.d/redis.list
$ sudo apt-get update && sudo apt-get install -y redis
$ redis-server --version
Redis server v=8.10.2 sha=00000000:1 malloc=jemalloc-5.3.0 bits=64 build=677c1e5d953828c4

7.3 NATS 2.15（消息总线 + 客户端 WebSocket）

从官方 release 安装 deb 包：

$ wget -O nats-server.deb https://github.com/nats-io/nats-server/releases/download/v2.15.1/nats-server-v2.15.1-amd64.deb
$ sudo dpkg -i nats-server.deb
Preparing to unpack nats-server.deb ...
Unpacking nats-server (2.15.1) ...
Setting up nats-server (2.15.1) ...
$ nats-server --version
nats-server: v2.15.1

⚠️ 下载实测：GitHub release 直连下载出现过一次文件截断（dpkg 报 unexpected end of file in archive magic version number），重下完整包（7,290,240 字节）后正常安装。

⚠️ 该 deb 不附带 systemd 单元，需按 8.2 节自建；且安装过程不创建系统用户，单元文件中直接用 root 运行，或先 useradd 专用账号并赋权数据目录。

写入 NATS 配置 /etc/nats-server.conf（JetStream 存储、8222 WebSocket、系统账号与 auth_callout 鉴权）。其中 NKey 分为两类：U 开头的是公钥（服务端配置里引用），SU 开头的是对应私钥种子（plugNmeet 配置里引用），生成一对后分开放：

websocket {
    port: 8222
    no_tls: true
}

jetstream: {
    store_dir: /var/lib/nats/jetstream
}

accounts {
    SYS: {
        exports: [
            {
                stream: "$SYS.ACCOUNT.PNM.>",
                accounts: [PNM]
            }
        ]
    }
    PNM: {
        jetstream: enabled
        imports: [
            {
                stream: {
                    account: SYS, subject: "$SYS.ACCOUNT.PNM.>"
                }
            }
        ]
        users: [
            {
                nkey: UB6MDZLJHLS4YXJMKES6QWWCXCMTDSEZHO5GMYJAUQ3PJDHCTKZ6PGGD
            }
        ]
    }
}

system_account: SYS

authorization {
    timeout: 5
    auth_callout {
        issuer: AC2DMAEHMXUQHIMIUOSRJI7FUN6GKKG55HAMWYO7O2OFWY7GLHXPUWJX
        auth_users: [ UB6MDZLJHLS4YXJMKES6QWWCXCMTDSEZHO5GMYJAUQ3PJDHCTKZ6PGGD ]
        account: PNM
        xkey: XCFAO7BHHJUGNY56CYQSCPXA32DASMHOX6WTAGT5RIPGVBZJAZEUJCE6
    }
}

准备 JetStream 数据目录（内网验证环境不做 TLS，生产建议在反代层做）：

$ sudo mkdir -p /var/lib/nats/jetstream

7.4 LiveKit 1.13（SFU 媒体服务器）

官方提供安装脚本（get.livekit.io，安装二进制到 /usr/local/bin）：

$ curl -sSL https://get.livekit.io | bash
$ livekit-server --version
livekit-server version 1.13.11

⚠️ 下载实测：get.livekit.io 与其背后的 GitHub 发布件在内网直连时出现 Connection reset by peer，改走代理后下载正常（二进制包 livekit_1.13.11_linux_amd64.tar.gz，19,464,037 字节）；能直连 GitHub 的网络环境无此问题。

写入 /etc/livekit.yaml（端口规划与 Redis 对接）：

port: 8146
rtc:
  port_range_start: 50000
  port_range_end: 60000
  tcp_port: 8147
  use_external_ip: false
  allow_tcp_fallback: true
redis:
  address: localhost:6379
  username: ""
  password: ""
  db: 0
room:
  auto_create: true
  enabled_codecs:
    - mime: audio/opus
    - mime: audio/red
    - mime: video/h264
    - mime: video/vp8
    - mime: video/vp9
    - mime: video/av1
logging:
  level: info
keys:
  APIlivekit1234: q1w2e3r4livekitsecret012345678901234
webhook:
  api_key: APIlivekit1234
  urls:
    - "http://127.0.0.1:8145/webhook"

要点：keys 里的 LiveKit key/secret 必须与第八节 plugNmeet 配置 livekit_info 完全一致，这是两个服务的互信凭证；use_external_ip: false 适配内网，公网部署改为 true。

八、plugNmeet 主配置与 systemd 托管

8.1 主配置文件

创建工作目录并写入 /opt/plugNmeet/config.yaml：

$ sudo mkdir -p /opt/plugNmeet/{log,upload,recording_files,artifacts}

client:
  port: 8145
  debug: false
  path: "/opt/plugNmeet/client/dist"
  api_key: APIkey1234567
  secret: q1w2e3r4plugnmeetsecret0123456789abcd
  token_validity: 10m
  webhook_conf:
    enable: false
    url: ""
    enable_for_per_meeting: false
  prometheus:
    enable: true
    metrics_path: "/metrics"
    username: ""
    password: ""
  copyright_conf:
    allow_override: false
    text: 'Powered by <a href="https://www.plugnmeet.org" target="_blank">plugNmeet</a>'
  bbb_join_host: "http://127.0.0.1:8145"

room_default_settings:
  max_duration: 0
  max_participants: 0
  max_num_breakout_rooms: 6
  max_preloaded_wb_file_size: 5mb

log_settings:
  log_file: "/opt/plugNmeet/log/plugNmeet.log"
  maxsize: 20
  maxbackups: 4
  maxage: 2
  log_level: "info"

livekit_info:
  host: "http://127.0.0.1:8146"
  api_key: APIlivekit1234
  secret: q1w2e3r4livekitsecret012345678901234

livekit_sip_info:
  enabled: false
  trunk_name: "pnm-inbound-trunk"
  phone_numbers: []

redis_info:
  host: localhost:6379
  username: ""
  password: ""
  db: 0
  default_ttl: 24h

database_info:
  driver_name: mysql
  host: localhost
  port: 3306
  username: plugnmeet
  password: q1w2e3r4
  db: plugnmeet
  prefix: pnm_
  charset: "utf8mb4"
  loc: "UTC"
  conn_max_lifetime: 4m
  max_open_conns: 10

nats_info:
  nats_urls:
    - "nats://127.0.0.1:4222"
  nats_ws_urls:
    - "ws://127.0.0.1:8222"
  account: PNM
  nkey: SUAMBUHCVL6ISLATV5RLBIZ5N4TSH5BCJ2XHCHD636PTAOCMXXAR7HLRNY
  auth_callout_issuer_private: SAAN4R7SHHPQ7ZSKJWBHACDMSYUGQ2L5QWDVUDCATOHKMSMC2E57KFGQIA
  auth_callout_xkey_private: SXAOPXSEKADPNY7JTT3CNSIRZARFJGFFFXTPRJDXISS4I3GFOFE4B6GFPM
  num_replicas: 1
  room_stream_name: "pnm-room-stream"
  default_ttl: 24h
  subjects:
    system_api_worker: "sysApiWorker"
    system_js_worker: "sysJsWorker"
    system_core_worker: "sysCoreWorker"
    system_public: "sysPublic"
    system_private: "sysPrivate"
    chat: "chat"
    whiteboard: "whiteboard"
    data_channel: "dataChannel"
  recorder:
    recorder_channel: "recorderChannel"
    recorder_info_kv: "pnm-recorderInfo"
    transcoding_jobs_subject: "pnm-RecorderTranscoderJobs"

upload_file_settings:
  path: "/opt/plugNmeet/upload"
  max_size: 50
  max_size_whiteboard_file: 30
  keep_forever: false
  allowed_types: ["jpg","png","jpeg","svg","pdf","docx","txt","xlsx","pptx","zip","mp4","webm","mp3"]

recorder_info:
  recording_files_path: "/opt/plugNmeet/recording_files"
  token_validity: 30m
  ping_timeout: 8s
  enable_del_recording_backup: true
  del_recording_backup_path: "/opt/plugNmeet/recording_files/del_backup"
  del_recording_backup_duration: 72h

analytics_settings:
  enabled: true

artifacts_settings:
  storage_path: "/opt/plugNmeet/artifacts"
  token_validity: 10m
  enable_del_artifacts_backup: true
  del_artifacts_backup_path: "/opt/plugNmeet/artifacts/trash"
  del_artifacts_backup_duration: 72h

insights:
  enabled: false

三个对位关系（错一个服务就起不来）：

配置项	必须与谁一致
`client.api_key/secret`	登录页输入的管理凭证、REST API 双头凭证
`livekit_info.api_key/secret`	`/etc/livekit.yaml` 的 `keys`
`nats_info.nkey` 等	`/etc/nats-server.conf` 的 NKey/issuer/xkey（私钥种子）

完整参数逐项释义见专栏《plugNmeet 2.5.3 配置参数详解》（发布后可从专栏目录进入）。

8.2 systemd 单元

mariadb、redis-server 随包自带单元；NATS、LiveKit、plugNmeet 三个单元需自建。

/etc/systemd/system/nats-server.service：

[Unit]
Description=NATS messaging server
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/nats-server -c /etc/nats-server.conf
Restart=always
RestartSec=10
SyslogIdentifier=nats-server

[Install]
WantedBy=multi-user.target

/etc/systemd/system/livekit-server.service：

[Unit]
Description=LiveKit SFU server
After=network.target redis-server.service
Wants=redis-server.service

[Service]
Type=simple
ExecStart=/usr/local/bin/livekit-server --config /etc/livekit.yaml --node-ip 127.0.0.1
Restart=always
RestartSec=10
SyslogIdentifier=livekit

[Install]
WantedBy=multi-user.target

/etc/systemd/system/plugnmeet.service：

[Unit]
Description=plugNmeet video conference server
After=network.target mariadb.service redis-server.service nats-server.service livekit-server.service
Wants=mariadb.service redis-server.service nats-server.service livekit-server.service

[Service]
Type=simple
WorkingDirectory=/opt/plugNmeet
Environment=LD_LIBRARY_PATH=/opt/speechsdk/lib/x64
ExecStart=/usr/local/bin/plugnmeet-server --config /opt/plugNmeet/config.yaml
Restart=always
RestartSec=10
SyslogIdentifier=plugNmeet

[Install]
WantedBy=multi-user.target

启动并设置开机自启：

$ sudo systemctl daemon-reload
$ sudo systemctl enable --now mariadb redis-server nats-server livekit-server plugnmeet

九、部署验证

9.1 服务状态

$ systemctl is-active mariadb redis-server nats-server livekit-server plugnmeet
active
active
active
active
active

9.2 Web 页面与健康检查

$ curl -s -o /dev/null -w 'login page HTTP %{http_code}\n' http://127.0.0.1:8145/
login page HTTP 200
$ curl -s http://127.0.0.1:8145/healthCheck
Healthy

9.3 服务端版本确认

$ journalctl -u plugnmeet --no-pager | grep -o 'version: 2.5.3' | head -1
version: 2.5.3

9.4 浏览器验证

浏览器打开 http://<服务器IP>:8145/（参会入口）与 http://<服务器IP>:8145/login（管理入口）。登录页不是用户名密码，而是输入 config.yaml 中的 api_key（示例 APIkey1234567）与 secret 后创建/进入会议。管理 API 的程序化调用（建房、发 token、查房间）见专栏 REST API 篇。

十、方案对比与选择建议

维度	源码编译（本文）	官方一键脚本
网络要求	内网可用（下载依赖需联网或代理一次）	需公网域名 + 80/443 + Let's Encrypt
技术栈形态	全部 systemd 原生服务，运维路径与普通 Linux 服务一致	脚本引入编排工具栈统一拉起五个服务
版本控制	可锁定任意 tag（含安全回滚到旧版）	跟随脚本与镜像更新节奏
升级方式	重新拉 tag 编译、替换二进制	重跑脚本
适用场景	内网/隔离环境、企业私有化交付、需要深度定制	有公网域名的标准 SaaS 化部署

建议：生产优先评估官方脚本（TLS、TURN、证书一键到位）；内网、等保/私有化场景用本文路径，再自行在前面挂 Nginx/HAProxy 补 TLS。

十一、常见问题

启动报 error while loading shared libraries: libMicrosoft.CognitiveServices.Speech.core.so（systemd 显示 status=127）：运行时找不到语音 SDK 库。按 5.2 节写入 /etc/ld.so.conf.d/speechsdk.conf 并 ldconfig，同时保留单元中的 Environment=LD_LIBRARY_PATH=/opt/speechsdk/lib/x64（本文实测即靠这两步解决）。
systemd 显示 status=203/EXEC：单元里 ExecStart 的二进制路径不存在或无执行位。确认已 cp 到 /usr/local/bin 并 chmod +x（本文实测踩过：只编译在源码目录、忘了安装）。
NATS 服务 status=217/USER：deb 包不创建系统用户，单元文件写了 User=nats-server 就会启动失败。要么 useradd nats-server 并 chown 数据目录，要么先用 root 运行（本文实测后者）。
go mod download 卡住或 refused：直连 Go 模块代理失败时改 GOPROXY=https://goproxy.cn,direct。
wget 下载大文件后解压报 unexpected end of file：mupdf 与 NATS deb 均实测出现过下载截断。先校验文件大小/可列出归档内容再继续，重试下载即可。
白板上传 PDF 不分页：检查 mutool 是否在 PATH 且版本 ≥1.28（mutool -v）。
客户端页面空白：确认 client.path 指向的是 client/dist（含 index.html 的那层），zip 解压后多出的 client/ 嵌套层是高频踩坑点（见第六节整理步骤）。

十二、卸载清理

$ sudo systemctl disable --now plugnmeet livekit-server nats-server
$ sudo rm -f /etc/systemd/system/{plugnmeet,livekit-server,nats-server}.service && sudo systemctl daemon-reload
$ sudo rm -rf /opt/plugNmeet /usr/local/bin/plugnmeet-server /usr/local/bin/livekit-server /opt/speechsdk \
  /etc/nats-server.conf /etc/livekit.yaml /etc/ld.so.conf.d/speechsdk.conf /usr/local/src/plugNmeet-server
$ sudo apt-get purge -y mariadb-server redis nats-server && sudo apt-get autoremove -y
$ sudo mariadb -e "DROP DATABASE IF EXISTS plugnmeet; DROP USER IF EXISTS plugnmeet@localhost;"

注意 /opt/plugNmeet/{upload,recording_files,artifacts} 存有会议上传文件与录制产物，卸载前确认已备份。

十三、参考链接

服务端源码仓库：https://github.com/mynaparrot/plugNmeet-server（本文 tag v2.5.3）
客户端发布页：https://github.com/mynaparrot/plugNmeet-client/releases
LiveKit：https://github.com/livekit/livekit/releases　NATS：https://github.com/nats-io/nats-server/releases
MariaDB 仓库脚本：https://mariadb.org/download/　Redis 官方源：https://packages.redis.io
站内相关文档：《plugNmeet 2.5.3 介绍与选型指南》