Docker 部署

官方镜像 nowledgelabs/mem 跑的就是和桌面版同一份后端，在 /app 直接提供网页应用，所有数据保存在主机上三个普通的 bind mount 目录里（./data、./config、./cache）。你用现成的工具备份就行——rsync、restic、tar、ZFS 快照都可以。

它处于预览阶段：已经发布、并在真实主机上做了端到端验证；运维相关的细节还会继续完善。

这条路适合你吗？

下面这些条件全部满足时，再选 Docker：

• 你有一台自己管的长期运行的主机——VPS、家庭 NAS、云主机、homelab 服务器等等——并希望 Mem 作为一个服务常驻在上面。
• 你已经在那台主机上用 Docker 跑其他长期服务，或者至少能在 shell 里跑几条命令、改一下 compose.yaml。
• 你想要一份集中部署的 Mem 服务器，让笔记本 / 手机 / 其他机器上的网页应用和 nmem CLI 都通过网络连接它。

如果上面任何一条不成立，直接装 桌面应用 即可——这是绝大多数用户的正确路径，并且你的数据仍然完全保留在自己的机器上。

支持的架构

镜像以多架构清单发布，docker pull nowledgelabs/mem:<版本> 在你常见的服务器架构上都能正确解析：

你不需要手动选架构——Docker 会自动按主机架构拉取对应镜像。如果你恰好在 Apple Silicon Mac 上用 Docker Desktop 做开发，它会拉到 arm64 镜像并能跑通，但这不是推荐路径：个人 Mac 上直接用桌面应用更省事。

快速开始

完整的 compose 套件在 community 仓库里：

git clone https://github.com/nowledge-co/community.git
cd community/docker
./nmemctl up

nmemctl 是这套部署的生命周期控制器，会启动容器、等待 /livez 通过，然后打印 API 密钥并告诉你网页应用的 URL。如果你已经有许可证：

./nmemctl license activate <BASE64 许可证>

其他命令：./nmemctl status（健康检查 + 密钥 + URL）、./nmemctl logs -f、./nmemctl upgrade <版本>、./nmemctl wipe（出厂重置）、./nmemctl help 查看完整命令列表。

如果你想手动来，三条命令也够了：

docker compose up -d
docker compose exec -T mem nmem key                                # 显示 API 密钥
docker compose exec -T mem nmem license activate <BASE64 许可证>    # 可选

然后在浏览器打开 http://<你的主机>:14242/app，按提示粘贴 API 密钥。

https://raw.githubusercontent.com/nowledge-co/community/main/skills/nowledge-mem-docker/SKILL.md

你能得到什么

• 一个容器里跑的就是和桌面版同一份 Mem 后端，/app 直接提供网页应用。
• 非 root 用户运行、镜像文件系统只读、所有数据都在 compose.yaml 旁边的三个本地目录里。不需要学 docker volume 那一套——直接用 rsync、restic、tar、ZFS 快照备份就行。
• 较小的镜像体积（压缩后约 1.3 GB），从源码直接构建，Python bundle 与桌面发行版完全一致。
• 多架构：一个 tag 在 amd64 与 arm64 主机上都通用。

API 密钥怎么找？

容器首次启动时 Mem 会自动生成一个 API 密钥。如果你错过了输出、丢了、想换一个，下面任意一条命令都行：

./nmemctl status                              # 重新打印密钥、许可证、URL、健康
./nmemctl key                                 # 只打印当前密钥
./nmemctl key --rotate                        # 轮换成新密钥
./nmemctl logs | grep -A 1 "API Key"          # 翻一下首次启动横幅

密钥保存在主机的 ./config/co.nowledge.mem.desktop/remote-access.json（容器内挂在 /etc/nowledge-mem/...），所以升级镜像不会丢。备份 ./config 就是在备份密钥。一旦轮换，现有的 Web 应用、MCP 客户端、远端机器上的 nmem CLI 都要重新粘贴新值，旧值立刻失效。

数据放在哪

三个本地目录就在 compose.yaml 旁边，由你来管。标准工具直接可用：

容器内进程以 UID 10001 运行；./nmemctl up 首次启动时会通过一次性辅助容器把这三个目录 chown 到 10001:10001，所以你完全不需要自己敲 chown 或 sudo。

./nmemctl upgrade <版本>（或手动的 docker compose pull && docker compose up -d）升级 Mem 时，这三个目录都会保留：许可证仍然有效，数据和对话原封不动，./cache 里的嵌入模型不必重新下载。只有 ./nmemctl wipe 这种「清空一切、从头开始」的操作才会把它们清掉——那是刻意的恢复出厂行为。

SELinux 用户（RHEL / Fedora / Rocky）：把 compose.yaml 里每个 bind mount 末尾加上 :Z，SELinux 就会替你重新打标签。默认未开启，因为首次应用是破坏性的，在非 SELinux 系统上无意义甚至会报错。

内存与数据规模增长

默认的 mem_limit: 4g 是按 被动使用 估算的：图谱、网页应用、空闲搜索。如果你打算在服务器上主动跑 AI Now 或 Feed 智能助理，需要把它调高。粗略对照：

如果某次文件上传或智能助理请求让界面卡在 500，最稳妥的恢复方式是 docker compose restart mem。镜像下次启动时会自动把图数据库的内部内存预算抬一档，相同的负载应该就能跑过去。如果问题反复出现，那就按上面的表把 mem_limit 调高。

在 arm64 单板机上（树莓派 5、Orange Pi 5 等），同样的对照表依然适用，但注意这些主板的 GPU 和其他加速器通常和主机共享 RAM，请给操作系统留足余量。

验证镜像来自我们

每次发布的镜像都附带了一份 Sigstore 证明。如果你想在拉取之前确认这个 tag 真的来自我们的构建流水线（而不是别处恰好同名），可以跑：

cosign verify docker.io/nowledgelabs/mem:0.8.6 \
  --certificate-identity-regexp='https://github.com/nowledge-co/mem/.github/workflows/release-docker.yml@.*' \
  --certificate-oidc-issuer='https://token.actions.githubusercontent.com'

通过的话，会显示构建时使用的 GitHub Actions 身份；失败说明你拉到的镜像不是我们流水线产出的，请不要使用。

证明挂在 manifest 上，所以同一条 cosign verify 对 amd64 和 arm64 都生效。

公网主机加 TLS

如果服务器从公网可达，并且你希望使用真实证书，同一个 community/docker/ 目录附带了 Caddy 备用方案：

export NOWLEDGE_DOMAIN=mem.example.com
export NOWLEDGE_LE_EMAIL=you@example.com
docker compose -f compose.yaml -f compose.tls.yaml up -d

你需要：把域名 DNS 指向这台主机，打开 80、443 端口供 Let's Encrypt 校验，并使用 Docker Compose v2.24.4 及以上版本（TLS overlay 用到了一个 YAML 合并标签，早期版本会静默忽略）。Caddy 会自动续期证书。

备份与迁移

两层方案，按你的迁移类型选其一：

卷级别快照（两端镜像版本完全一致，恢复最快）：

./nmemctl export                    # 停容器，打包 ./data ./config ./cache，重启
./nmemctl export --no-cache         # 跳过可重建的 cache，归档更小
./nmemctl import mem-export-<host>-<ts>.tar.gz   # 在新主机上恢复

应用级别导出（跨版本，或从 .deb / 桌面版迁过来 —— 使用与桌面版「导出到文件」相同的可移植 JSONL 格式）：

./nmemctl backup-app                # 生成 mem-app-export-<host>-<ts>.zip
./nmemctl restore-app mem-app-export-<host>-<ts>.zip

如果想了解应用里这套可移植导出格式，请阅读备份、导出与导入。

两种方式都会有意丢掉 machine_id：目的主机会拿到全新的设备身份，首次启动时重新激活许可证（消耗一次设备额度）。迁移成功后请下线源服务器——双跑会让状态分叉、把许可证额度多花一份。

你也可以直接对 ./data 和 ./config 跑 rsync、restic、borg、ZFS 快照或 tar——它们就是普通的主机目录。如果要绝对一致的快照，先 ./nmemctl down，做完再 ./nmemctl up。

跨架构迁移（比如从 amd64 VPS 迁到 arm64 NAS）请走 backup-app / restore-app：卷级别快照绑定了源架构的某些落盘投影，跨架构恢复不一定能直接还原。

在网页里升级（可选）

默认情况下，给自托管的 Mem 升级需要 SSH 上去跑一次 ./nmemctl upgrade <版本>。如果你想直接在 Mem 的网页里完成升级，启用一次自动升级：

./nmemctl auto-update enable

这一步会生成本机专用的随机令牌，加上一个负责升级的伴随容器，并允许从浏览器触发 Install。之后：

• 标题栏徽章：发布新版本时亮起，和桌面应用提示更新的方式一致。
• 设置 → 服务器 卡片：显示当前版本、最新版本、Download 按钮（后台拉取，无停机）以及 Install 按钮（约 30 秒停机，重建容器前会先做一次快照）。
• 可以跳版本升级。 如果你在 0.8.4 而最新是 0.8.6，Install 会直接升级到 0.8.6。Schema 迁移会在新镜像首次启动时按顺序执行。

启用前要了解：

• 负责升级的伴随容器会挂载 /var/run/docker.sock，这就是为什么默认不开。这个容器拥有等同于宿主 root 的权限；Mem 容器本身从来不接触 socket。
• 远端 Install 是显式开关。 只读的更新检查在网页上一直可用，但 Download 和 Install 默认只接受 loopback 请求，需要 NOWLEDGE_ADMIN_REMOTE_OPS=1 才打开。auto-update enable 会替你设置这个开关，因为在浏览器里点 Install 本质上是在让服务器改变自身状态。只在可信网络上启用。
• 每次 Install 之前，Mem 会先把 ./data 和 ./config 打包到 ./cache/_pre-upgrade-<时间戳>.tar.gz。最近 3 份快照会保留在本机。如果新镜像启动失败，网页上会显示快照路径，SSH 上去执行 ./nmemctl import <路径> --force 就能还原到升级前的状态。

./nmemctl auto-update status              # 状态、最近一次拉取、保留的快照
./nmemctl auto-update rotate              # 轮换升级令牌
./nmemctl auto-update upgrade             # 升级伴随容器自身的镜像
./nmemctl auto-update disable             # 移除伴随容器，保留所有快照

完整运维笔记

如果你想看完整的运维约定——每一个环境变量、安全加固细节、设备身份不变式、详细的故障排查方法——请阅读 community 仓库里的 community/docker/README.md。

相关

• 安装 — 桌面应用路径，也是绝大多数用户该走的路径。
• Linux 服务器部署 — .deb + systemd 安装路径，适合更偏好包管理而非容器的 Linux 服务器。
• 备份、导出与导入 — 应用级别的可移植导出格式与恢复流程。
• 远程访问 — Access Anywhere 密钥、API 访问、多设备同步。同样适用于 Docker 部署。
• LLM 提供商 — 后台智能（每日简报、洞见、图谱扩充）需要先配置。
• 故障排除 — 常见运维问题，包括无头容器部署路径。