顺着这个问题查下去，发现真正有价值的东西不在「归档坏了」本身，而在于：一条对话在本地到底被存成了多少份、分散在多少个地方。把这张地图画清楚之后，归档失败的原因、为什么应用自带的「删除」删不干净、以及一个彻底删除的工具该怎么写，就都顺理成章了。

本文分两部分：前半部分是实测出来的本地存储结构，后半部分是据此写的清理工具。

文中的盘符、目录名、线程 ID 和对话标题均为脱敏示例，请替换成自己的实际值。

一、先确定「桌面端」是哪个程序

这一点比想象中重要。OpenAI 现在有好几个同名或近名的客户端，路径也不一样：

判断方法很直接：

1
2

Get-Process | Where-Object { $_.ProcessName -match 'chatgpt|codex' } |
  Select-Object ProcessName, Id, Path

如果 Path 落在 WindowsApps 下面（形如 ...\WindowsApps\OpenAI.Codex_<版本>_x64__<哈希>\app\ChatGPT.exe），那就是打包安装的桌面客户端。

它的本地数据根是 %USERPROFILE%\.codex，不是 AppData 里的某个目录。这一点容易猜错——.codex 是个隐藏目录，很多人第一次找根本不会往家目录想。

二、归档为什么一直失败

归档是本地操作，不是云端操作

这一点从日志能直接确认。翻客户端日志目录，归档动作打出的是：

1
2
3
4
5
6
7
8

[electron-message-handler] Archive requested conversationId=<线程ID> source=recent_tasks_menu
[AppServerConnection] response_routed ... method=thread/archive ... errorCode=-32600
error [electron-message-handler] Request failed
  error={"code":-32600,"message":"no rollout found for thread id <线程ID>"}
  failureReason=rollout_not_found
info  [electron-message-handler] Archive skipped because thread has no active rollout
warn  [electron-message-handler] Failed to persist inactive thread archive
  errorMessage="Inactive thread archive did not persist"

而整份日志里没有任何 backend-api/conversation 之类的云端请求。也就是说：桌面端侧栏里那条对话的归档，走的是本地 thread/archive，没有碰云端会话。

归档的动作是「把文件搬走」

进一步能看出，thread/archive 需要把这条对话的 rollout 文件搬走：

1

%USERPROFILE%\.codex\sessions\2026\09\24\rollout-2026-09-24T17-07-29-<线程ID>.jsonl

于是失败条件就很清楚了——数据库里还有这条线程的记录，但它指向的文件已经不存在了：

1
2
3
4

state_5.sqlite → threads 表里 9 条记录
其中 3 条：rollout_path 指向的文件不存在
           → 归档时找不到文件 → 报 no rollout found → 界面显示「归档失败」
其余 6 条：文件都在 → 归档正常（日志里 errorCode=null）

这也解释了一个反直觉的现象：这些对话在界面上能正常打开、能看历史，但就是归档不了。原因在下一节。

文件是怎么没的

这点只能给推断，不能当结论。几条证据指向客户端的 rollout 迁移流程：

• state_5.sqlite 里有 rollout_migration_state 表，记录 legacy_to_paginated_v1 迁移检查到哪条线程（last_checked_thread_id / last_checked_thread_created_at）；
• 该水位线指向的线程，创建时间晚于那 3 条出问题的线程，说明它们确实在迁移的扫描范围内；
• 记录跳过的表 rollout_migration_skipped_rollouts 为空，rollout-migrations/ 目录也是空的。

具体是谁删的、为什么没同步清理数据库记录，我没有官方文档可查。但从结果看，文件被消费掉、threads 行留了下来。

顺带一个实用发现：原始的 rollout 文件已经没了，但它原本多大是能算出来的。
thread_history_1.sqlite 的 thread_history_projection_state 表里有一列
next_rollout_byte_offset，记录投影已经读到原文件的第几个字节。
这三个值分别是 2493389 / 93247 / 372304 字节——这就是三个文件的原始大小。

三、完整存储地图：一条对话可能散落在 20 个地方

这是全文最想留下来的东西。桌面端并没有把一条对话存成「一个文件」或「一张表」，而是拆得很细。下表是逐项实测出来的，其中 goals / queue 之类的几项在多数情况下是空的，但清理时不能假设它们一定为空：

第 14 项值得单独展开，因为它是残留最多的地方。.codex-global-state.json 里按线程 ID 索引的键家族至少有这些：

1
2
3
4
5
6
7
8
9
10
11
12
13

prompt-history.<线程ID>                          输入历史
heartbeat-thread-permissions-by-id.<线程ID>      权限心跳
thread-descriptions-v1.<线程ID>                  自动描述
thread-writable-roots.<线程ID>                   可写根目录列表
thread-project-assignments.<线程ID>              项目归属
thread-project-membership-host-ids.<线程ID>      所属主机
client-thread-bindings-v1.<客户端线程ID> = <线程ID>   绑定关系
electron-remote-hosted-pip-task-visibility-state.<线程ID>
thread-reference-capability:<线程ID>             顶层键，形如 <前缀>:<ID>
thread-client-id-v1:local%3A<线程ID>             顶层键（ID 被 URL 编码）
thread-tab-routes-v1:<线程ID>                    顶层键
codex-writing-block-deleted-thread-v1:<线程ID>   删除标记
app-server-projects-migration-by-host.*.pendingThreadAssignmentIds  ← 数组里存裸 ID

注意最后一行：ID 还会以数组元素的形式出现，所以清理逻辑必须能递归处理任意嵌套的 JSON，不能只盯着键名。

四、两个关键机制

1. 界面能显示，靠的是数据库；能归档，靠的是文件

这是理解整件事的钥匙。

thread_history_1.sqlite 的 thread_items 是一份投影（projection）——客户端把 rollout 流水按字节逐个读进来，解析成消息条目存进 SQLite。界面渲染历史时读的是这张表，不是那个 jsonl 文件。

所以当 rollout 文件丢失后：

• thread_items 里的消息还在 → 界面照常显示，对话能打开；
• 归档要找文件搬走 → 找不到，失败。

两者一旦脱钩，就会出现「能看不能删」这种别扭状态。

2. 删除之后，正文还躺在 SQLite 的空闲页里

SQLite 删行只是把页标记为空闲，页里的字节不会立刻被抹掉。可以用 PRAGMA freelist_count 看当前有多少空闲页：

1
2

PRAGMA freelist_count;   -- 空闲页数
PRAGMA page_count;       -- 总页数

只要空闲页不回收，对话正文理论上仍然可以从数据库文件里被扫描出来。所以「彻底删除」的最后一步必须是 VACUUM——它会重建整个数据库文件，把这些字节真正清掉。

验证方法很朴素：删完之后直接把数据库当二进制文件搜一下关键字。

1
2

raw = open(db_path, "rb").read()
print(raw.count(b"<关键字>"))   # VACUUM 之后应为 0

五、应用自带的删除为什么不彻底

实测方式很直接：客户端里早就删掉的旧对话，拿它的 ID 回全局状态里搜，仍然能搜到：

1
2
3
4

prompt-history.<已删除的线程ID>                    ← 还在
heartbeat-thread-permissions-by-id.<已删除的线程ID> ← 还在
thread-reference-capability:<已删除的线程ID>        ← 还在
codex-writing-block-deleted-thread-v1:<已删除的线程ID> ← 还在

（有意思的是 thread-descriptions-v1 那条确实被清掉了，说明自带删除清了一部分键，但没清全。）

这就意味着：如果你在意的是「这条对话在我机器上不要留下任何痕迹」，自带删除是不够的。

六、工具设计

需求很明确：给定一条或多条对话，把上面那张地图里的痕迹一次性清干净。工具叫 codex-chat-cleaner，单文件 Python，只用标准库。

1. 先找 rollout，再确定要删哪些 ID

这是设计里最容易踩坑的地方。

一条对话可能派生出「子代理」线程（例如自动审查用的 guardian）。它们的 rollout 文件长这样：

1
2
3
4
5
6

{"type":"session_meta","payload":{
  "session_id":"<父线程ID>",
  "id":"<子线程自己的ID>",
  "parent_thread_id":"<父线程ID>",
  "thread_source":"guardian_review"
}}

也就是说，子代理在 threads 表里是一条独立的行。

如果只删父对话、却把子代理的 rollout 文件也一起删掉，就会制造出两个新的「有记录没文件」的孤儿——正好复现本文开头那个归档失败的成因。

所以流程必须是：先扫 rollout 找出子代理 ID，把它们加入删除集合，再统一删数据库。而不是反过来。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

def find_rollouts(codex_home, ids, want_children):
    """返回 (本线程 rollout, 子代理 rollout, 子代理自己的线程 id)。"""
    own, children, child_ids = set(), set(), set()
    for root in (sessions_dir, archived_sessions_dir):
        for dirpath, _dirnames, filenames in os.walk(root):
            for fn in filenames:
                if not fn.endswith(".jsonl"):
                    continue
                sid, oid, parent = read_session_meta(os.path.join(dirpath, fn))
                if oid in ids:
                    own.add(...)
                elif sid in ids or parent in ids:
                    if want_children:
                        children.add(...)
                        if oid:
                            child_ids.add(oid)      # ← 关键：把子线程也纳入删除范围
    return own, children, child_ids

2. 迁移水位线要回退，不能留悬空引用

如果被删线程恰好是 rollout_migration_state 指向的那一条，水位线就指向了一个不存在的线程。工具会把它回退到「创建时间不晚于原水位线、且仍然存活」的最近一条；一条都不剩就置空。

这条纯粹是为了不留悬空引用——语义是我从表结构和实测行为推断的，不是官方文档，所以实现上只做「不指向被删线程」这一点，不改变迁移本身的其它行为。

3. 删除范围做成开关

不是所有痕迹都同等重要，所以范围是可配的：

日志默认关，是因为排查问题时它有用；而且日志里混着其它对话的内容，误伤成本高。

4. 递归清理全局状态

全局状态的形状不固定——键名里可能有 ID、值可能是 ID、数组元素可能是 ID、值里的路径也可能含 ID。所以清理函数必须递归处理所有形态：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

def purge_json(node, ids, stats):
    if isinstance(node, dict):
        out = {}
        for k, v in node.items():
            if isinstance(k, str) and hit(k, ids):      # 键名含 ID
                stats["keys"] += 1
                continue
            if isinstance(v, str) and hit(v, ids):      # 值就是 ID
                stats["keys"] += 1
                continue
            out[k] = purge_json(v, ids, stats)          # 继续往下钻
        return out
    if isinstance(node, list):
        res = []
        for x in node:
            if isinstance(x, str) and hit(x, ids):      # 数组元素是 ID
                stats["items"] += 1
                continue
            res.append(purge_json(x, ids, stats))
        return res
    return node

一个刻意的取舍：数组被清空时保留空数组，不连键一起删。因为不知道客户端是否会因为缺键而报错，留个空数组更稳。

5. 记忆文件按「块」回收，不是按行

memories/MEMORY.md 是有层级的：

1
2
3
4
5
6
7
8
9
10
11
12
13

# Task Group: <项目>
scope: ...
applies_to: ...

## Task 1: <任务标题>

### rollout_summary_files

- rollout_summaries/<文件>.md (..., thread_id=<线程ID>, ...)

### keywords

- <关键词>...

只删那行 thread_id= 是不够的——### keywords 里的关键词、以及 ## User preferences、## Reusable knowledge 这些小节的正文，都还是从这条对话提炼出来的。

所以回收逻辑是按层级判断：

1. ## 小节里 rollout_summaries/ 条目若全部指向被删线程 → 整个小节删掉；
2. 其余仍含被删 ID 的行 → 逐行删掉；
3. # Task Group 块清理后不再剩任何 ## Task → 整块删掉（此时它的偏好、知识、失败记录等小节，都只是已消失 Task 的附属内容）。

同理，raw_memories.md 是按 ## Thread `<线程ID>` 分块的，整块删除即可。

6. 安全措施

• 检测进程：ChatGPT.exe / codex.exe 在跑就拒绝执行。客户端会把全局状态从内存整体重写，开着改等于白改。
• 先备份再动手：所有受影响的文件复制到 backups\<UTC时间戳>\，包含原库（连 -wal / -shm）、被删文件的副本、线程原始行快照（thread_snapshot.json）、以及路径清单（manifest.json）。
• 事务 + 原子写：数据库改动包在 BEGIN IMMEDIATE 里，出错回滚；JSON 用「临时文件 + os.replace」写，不会留半截文件。
• 提交后 VACUUM：清掉空闲页里的正文残留。
• 默认干跑：先列出将执行的每一条（哪张表删几行、删哪些文件、全局状态移除几个键），要手输 DELETE 才真正执行。

七、使用

1
2
3
4
5
6
7

cd D:\tools\codex-chat-cleaner

python cleaner.py --list          # 列出所有对话（含 rollout 是否缺失）
python cleaner.py                 # 交互式 TUI
python cleaner.py --scan --id <线程ID>        # 残留自检
python cleaner.py --id <线程ID> --dry-run     # 只看计划
python cleaner.py --id <线程ID>               # 执行（要手输 DELETE 确认）

TUI 的按键：

列表长这样，rollout 缺失的会直接标出来——这类正是会归档失败的：

1
2
3
4
5
6
7
8
9

Codex 对话清理器  (4 条对话)
─────────────────────────────────────────────────────
[ ] 11111111  示例对话 A           09-28 08:40   78条
[x] aaaaaaaa  示例对话 B           09-24 17:07   53条  rollout缺失
[ ] bbbbbbbb  示例对话 C           09-24 14:00    5条  rollout缺失
[ ] cccccccc  Guardian review      09-24 09:45    0条
─────────────────────────────────────────────────────
已选 1 条
↑↓ 移动   Space 勾选   a 全选/取消   Enter 预览   s 范围设置   r 残留自检   q 退出

残留自检怎么读

删完会自动全盘再扫一遍。有两类命中是正常的，工具会标注出来：

1. 其他对话正文提及 <ID>（正常，未改动）——别的对话里提到过这个 ID。那段正文属于别的对话，不该动；
2. logs_2.sqlite [logs.thread_id]——日志行，默认保留。

真正要看的是输出的「其中需关注 N 处」，正常情况下应为 0。

八、实测结果

拿三条「有记录、没文件」的对话跑完整流程：

删完后按二进制搜数据库文件，state_5.sqlite、codex-dev.db、memories_1.sqlite、session_index.jsonl、cap_sid 全部为 0 命中。

唯一「残留」的是 thread_history_1.sqlite 里的一批字节——追下去发现它们全部属于另一条仍然存活的对话的消息正文（那条对话的正文里提到了这些 ID）。这类命中是正常的，工具的自检会把它标成「其他对话正文提及」。

九、边界、风险与恢复

这个工具不能做到的：

• 不恢复已经丢失的 rollout 内容。归档失败那几条的文件是真没了，删除只是把残缺记录一并清掉；
• 不动云端会话。本文全程是本地数据，网页端账号里的对话不受影响；
• 不修客户端自身的 bug。它清的是残留，不是修行为。

风险与恢复：

删除不可逆（除备份外）。出问题时：

1
2
3
4
5

# 1. 先退出客户端
# 2. 把 orig/ 里的文件按原名覆盖回去
Copy-Item "backups\<时间戳>\orig\state_5.sqlite" "$env:USERPROFILE\.codex\state_5.sqlite" -Force
# -wal / -shm 若有备份一并覆盖
# 3. 按 manifest.json 里的 removed_files[].path 把 files/ 里的文件放回原路径

备份里的 thread_snapshot.json 保存了被删线程在 threads / thread_items / thread_turns 里的完整原始行，必要时可以手工 INSERT 回去。

一个已知限制： 子代理 ID 只能从 rollout 文件里反查。如果先删了一次（当时没开日志范围），之后想再清日志里属于子代理的那些行，需要手动把子代理 ID 也传进去：

1
2

python cleaner.py --logs --yes `
  --id <父线程ID> --id <子代理ID> --id <另一个子代理ID>

十、下载

• 脚本：https://imgs.wybyte.top/file/codex-chat-cleaner/cleaner.py
• 说明文档：https://imgs.wybyte.top/file/codex-chat-cleaner/README.md

README 里记录了完整的落点清单和恢复步骤。

附录：几个值得留意的实现细节

1. 删库时顺手 VACUUM 会拖慢速度，但省不掉。 只在被改动的小库上做（几百 KB 到几 MB），30MB 的日志库单独给开关。

2. TUI 的宽度计算要按东亚字符算。 中文标题按 1 个字符算宽度会导致整列错位：

1
2

def char_w(ch):
    return 2 if unicodedata.east_asian_width(ch) in ("W", "F") else 1

按键用标准库 msvcrt.getwch()，方向键是 \x00 / \xe0 前缀加一个字母，不需要任何第三方依赖。

3. 描述和预览共用同一份「计划对象」。 先构造出 Plan（里面是一串 Op），预览页遍历它打印，执行页遍历它运行。这样预览看到的就是真正会执行的，不会出现两边逻辑漂移。

4. 扫残留时要区分「该删的」和「别人正文里提到的」。 后者如果一并删掉，就等于改了另一条对话的历史，所以自检里必须把两类分开报。

相关阅读

• 清理 Codex 对话残留失效索引：解决侧边栏打不开或反复报错 —— 处理的是「孤儿索引」，本文的工具是在它的基础上把范围扩到了全局状态、记忆、日志等全部落点。

本文记录如何使用 Mender 建立一套“总部统一发布版本，各地区服务器主动获取并升级”的系统。

目标场景如下：

• 总部维护一个 Mender Server；
• 前端、后端等业务服务通过 Docker Compose 运行；
• 每个地区有一台或多台 Linux 服务器；
• 地区服务器只需要主动访问总部的 HTTPS 地址，不开放升级端口；
• 总部可以按地区分组、灰度发布、查看结果并停止异常批次；
• 发布制品必须经过签名，地区服务器拒绝未签名或被篡改的制品；
• 应用升级失败时能够回退容器版本；
• 涉及数据库变更时，由业务脚本完成备份、迁移和恢复。

本文重点介绍 Docker Compose 应用升级。Mender 的 A/B 根文件系统适合操作系统整体升级，但需要磁盘分区、bootloader 和系统镜像适配，不能通过安装一个客户端直接获得，文末会单独说明。

本文版本和环境

Mender 的软件仓库、Chart 和命令会继续变化。本文固定以下示例环境，实际部署前应再次检查官方 Supported releases 页面。

文中的域名、账号、Bucket、密钥、镜像地址和地区编号都是示例，不能原样用于生产。

Mender各组件分别做什么

先明确 Mender 中几个容易混淆的概念。

在本文场景中，每台地区服务器都作为一台 Mender Device。总部创建 Deployment 后，地区服务器在下一次轮询时收到任务。

推荐架构

    flowchart TB    subgraph HQ[总部]        GIT[业务代码仓库] --> CI[CI/CD Runner]        CI --> BUILD[构建容器镜像和 Compose]        BUILD --> ART[生成并签名 .mender]        ART --> MS[Mender Server]        MS --> DB[(MongoDB)]        MS --> OBJ[(S3 对象存储)]        MS --> CACHE[(Redis)]        MS --> MQ[(NATS)]    end    MS -->|HTTPS 443| E1[华东地区服务器\nMender Client + Compose Module]    MS -->|HTTPS 443| E2[华南地区服务器\nMender Client + Compose Module]    MS -->|HTTPS 443| E3[西北地区服务器\nMender Client + Compose Module]    E1 --> D1[Docker Compose 业务服务]    E2 --> D2[Docker Compose 业务服务]    E3 --> D3[Docker Compose 业务服务]  

Mender Client 主动发起所有通信，因此地区服务器只需要出站访问总部 443/TCP。总部不需要 SSH 到地区服务器，地区防火墙也不需要为 Mender Client 开放入站端口。

这里的“同步升级”是同一 Deployment 内的批量升级，不代表所有服务器在同一秒开始。设备何时拿到任务取决于自己的轮询周期。生产环境也不建议同时升级全部地区，而应该先试点再逐步扩大。

部署位置规划

如果使用 Hosted Mender，总部 Kubernetes、MongoDB、Redis、NATS 和对象存储都由 Mender 官方维护。企业只需要部署 CI/CD 工具、地区客户端和业务升级脚本。

从哪里下载

所有组件都应从官方地址获取。

生产环境不要使用 experimental APT 源、main 镜像标签或不固定版本的安装脚本输出。应先在测试环境验证，再固定具体软件和 Chart 版本。

第一阶段：搭建Mender Server评估环境

第一次接触 Mender 时，建议先用 Docker Compose 搭建一次评估环境，熟悉设备接入、上传 Artifact 和创建 Deployment。这个环境配置简单，但证书、依赖和资源配置都不符合生产要求。

准备总部测试服务器

官方评估环境最低要求为：

• x86_64 或 arm64；
• 16 GiB 内存；
• 2 个 vCPU；
• 50 GiB 可用磁盘；
• Docker Engine；
• Docker Compose 2.23.1 或更新版本。

确认环境：

1
2
3
4

docker version
docker compose version
free -h
df -h

这一步的作用是确认容器运行环境和磁盘满足 Mender 多个微服务同时启动的要求。

配置评估域名

在测试服务器的 /etc/hosts 中增加：

1
2

127.0.0.1 docker.mender.io
127.0.0.1 s3.docker.mender.io

官方评估环境内置证书使用这两个域名。该配置只是让本机能够把域名解析到评估环境，不能作为生产 DNS 方案。

下载并启动评估服务器

1
2
3
4
5
6
7

git clone -b v4.1.0 \
  https://github.com/mendersoftware/mender-server.git \
  mender-server

cd mender-server
export MENDER_IMAGE_TAG=v4.1.0
docker compose up -d

每条命令的作用如下：

• git clone -b v4.1.0：下载固定版本的官方 Compose 和配置；
• MENDER_IMAGE_TAG：指定各个 Mender 服务使用的镜像版本；
• docker compose up -d：后台启动 API Gateway、UI、设备认证、部署、库存和存储等服务。

检查容器：

1
2

docker compose ps
docker compose logs --tail=100

只有所有关键容器都正常运行后，才继续创建管理员。

创建管理员

1
2
3
4
5
6

export MENDER_USERNAME='admin@docker.mender.io'
export MENDER_PASSWORD='Replace-With-A-Strong-Password'

docker compose run --name create-user useradm create-user \
  --username "$MENDER_USERNAME" \
  --password "$MENDER_PASSWORD"

useradm 是 Mender 的用户管理服务。这条命令直接在服务端创建第一个管理用户。

浏览器访问：

1

https://localhost

评估环境使用自签名证书，浏览器会提示不受信任。这个警告只能在隔离测试环境临时接受，生产环境必须配置有效证书。

停止和清理评估环境

只停止容器并保留数据：

1

docker compose stop

删除容器、Volume 和全部测试数据：

1

docker compose down -v --remove-orphans

第二条命令会删除设备、用户、Artifact、Deployment 和日志，不能在需要保留数据的环境执行。

第二阶段：生产部署Mender Server

生产环境官方推荐使用 Kubernetes + Helm。经过官方验证和支持的 Kubernetes 环境主要是 EKS、AKS 和 GKE；本地 k3s 可以用于 PoC，但不能因为 Helm 安装成功就视为完整生产集群。

生产依赖

Mender Server 生产环境至少需要：

官方 Chart 内可以带 MongoDB、Redis 和 NATS 子 Chart，但这些更适合测试或 PoC。生产环境应使用独立维护的服务。

Mender Server 本身的参考资源为：

准备Kubernetes和Helm

如果只是验证 Helm 流程，可以在 Ubuntu 测试机安装 k3s：

1
2
3
4
5

curl -sfL https://get.k3s.io -o install-k3s.sh
less install-k3s.sh
sudo sh install-k3s.sh --write-kubeconfig-mode 644
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
kubectl get nodes

先下载并审查脚本，再以 root 执行。kubectl get nodes 出现 Ready 表示控制面可用。

安装 Helm：

1
2
3
4
5
6

curl -fsSL \
  https://raw.githubusercontent.com/helm/helm/master/scripts/get-helm-3 \
  -o get-helm-3.sh
less get-helm-3.sh
bash get-helm-3.sh
helm version

生产环境应使用企业已经维护的 Kubernetes 集群，不应照搬单节点 k3s。

准备域名和TLS

将以下域名解析到 Kubernetes Ingress 或 Load Balancer：

1

mender.example.com

Ingress 必须满足：

• HTTP 自动跳转 HTTPS；
• 对 mender.example.com 提供有效 TLS 证书；
• 大文件上传超时足够长；
• 如果负载均衡器要求健康检查，使用 /ui；
• Artifact 上传大小不能被 Ingress 默认限制拦截。

可以使用 cert-manager 自动申请证书：

1
2
3
4
5
6
7

helm repo add jetstack https://charts.jetstack.io
helm repo update
helm upgrade --install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --version v1.16.1 \
  --set crds.enabled=true

这一步的作用是让 Kubernetes 自动申请、保存和续期 X.509 证书。实际使用 Let’s Encrypt 还是企业 CA，应由网络和安全策略决定。

准备对象存储

生产环境建议使用 AWS S3、Cloudflare R2、Google Cloud Storage 的 S3 兼容接口或 Azure Blob Storage。对象存储负责保存真正体积较大的 .mender 文件，MongoDB 只保存元数据。

准备以下信息：

1
2
3
4
5

export STORAGE_BUCKET='mender-artifacts-prod'
export STORAGE_ENDPOINT='https://s3.example.com'
export AWS_REGION='us-east-1'
export AWS_ACCESS_KEY_ID='Replace-With-Access-Key'
export AWS_SECRET_ACCESS_KEY='Replace-With-Secret-Key'

生产中不要把密钥写进 Shell 历史或提交到 Git，应放在 Kubernetes Secret、Vault 或云 Secret Manager 中。示例使用环境变量只是为了说明 Chart 需要哪些值。

准备Mender Helm配置

先添加 Mender Chart 仓库并查看可用版本：

1
2
3

helm repo add mender https://charts.mender.io
helm repo update
helm search repo mender/mender --versions

创建 mender-values.yml：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

ingress:
  enabled: true
  ingressClassName: nginx
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
    nginx.ingress.kubernetes.io/proxy-body-size: "0"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "7200"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "7200"
  path: /
  hosts:
    - mender.example.com
  tls:
    - secretName: mender-ingress-tls
      hosts:
        - mender.example.com

global:
  url: https://mender.example.com
  s3:
    AWS_URI: https://s3.example.com
    AWS_BUCKET: mender-artifacts-prod
    AWS_REGION: us-east-1
    AWS_ACCESS_KEY_ID: Replace-With-Access-Key
    AWS_SECRET_ACCESS_KEY: Replace-With-Secret-Key

api_gateway:
  storage_proxy:
    enabled: true
    url: https://s3.example.com
    customRule: "PathRegexp(`^/mender-artifacts-prod`)"

这份配置完成三件事：

1. 通过 Ingress 暴露 Mender UI 和 API；
2. 告诉 Mender 自己的外部访问地址；
3. 指定 Artifact 保存到哪个对象存储。

不同云厂商、Ingress Controller 和对象存储的配置不完全相同。上面的文件是结构示例，生产部署应按实际服务修改，并将凭据改为 Secret 引用。

使用外部MongoDB

创建保存连接串的 Secret：

1
2
3
4
5

kubectl create namespace mender

kubectl -n mender create secret generic mender-mongo \
  --from-literal=MONGO='mongodb://mender-user:Replace-With-Password@mongo-1.example.com:27017,mongo-2.example.com:27017,mongo-3.example.com:27017/mender?replicaSet=rs0' \
  --from-literal=MONGO_URL='mongodb://mender-user:Replace-With-Password@mongo-1.example.com:27017,mongo-2.example.com:27017,mongo-3.example.com:27017/mender?replicaSet=rs0'

在 mender-values.yml 中增加以下内容；如果文件已经存在 global，必须把 mongodb 合并到原有 global 下，不能再创建一个同级重复键：

1
2
3
4
5
6

global:
  mongodb:
    existingSecret: mender-mongo

mongodb:
  enabled: false

existingSecret 让 Mender 服务读取外部 MongoDB 连接；mongodb.enabled: false 禁用 Chart 内置的评估数据库。

Redis、NATS 和对象存储也应采用同样原则：连接企业维护的外部服务，并关闭对应的测试子 Chart。具体字段随 Chart 版本变化，应以安装版本的 values.yaml 为准：

1

helm show values mender/mender > mender-default-values.yml

安装Mender Server

前面已经添加过 Mender Chart 仓库。先确认列表，从中选择经过测试的版本，然后固定 Chart：

1
2
3
4
5
6
7
8
9

export MENDER_CHART_VERSION='Replace-With-Verified-Chart-Version'

helm upgrade --install mender mender/mender \
  --namespace mender \
  --create-namespace \
  --version "$MENDER_CHART_VERSION" \
  --wait \
  --timeout 20m \
  -f mender-values.yml

不要在生产中省略 --version。固定 Chart 可以避免某次重新部署时自动拿到不兼容的新版本。

检查部署：

1
2
3

kubectl -n mender get pods
kubectl -n mender get ingress
kubectl -n mender get events --sort-by=.lastTimestamp

所有核心 Pod 应为 Running 或完成预期 Job，Ingress 应显示正确域名和地址。

创建第一个管理员

1
2
3
4
5
6
7
8

USERADM_POD=$(kubectl -n mender get pod \
  -l 'app.kubernetes.io/component=useradm' \
  -o name | head -1)

kubectl -n mender exec "$USERADM_POD" -- \
  useradm create-user \
  --username 'admin@example.com' \
  --password 'Replace-With-A-Strong-Password'

浏览器访问：

1

https://mender.example.com

如果页面打不开，依次检查 DNS、Ingress 地址、TLS Secret、Ingress 日志和 Mender Pod 状态。

生产备份

Mender Server 至少需要分别备份：

• MongoDB：设备身份、用户、库存、Deployment 和发布元数据；
• 对象存储：全部 .mender Artifact；
• Kubernetes Secret：服务连接串、证书和部署配置；
• Helm values：去除明文密钥后纳入配置版本管理。

只备份 MongoDB 不能恢复 Artifact 文件，只备份对象存储也不能恢复设备和发布记录。恢复演练必须验证 UI 登录、设备认证、Artifact 下载和历史 Deployment 查询。

第三阶段：安装地区服务器Mender Client

下面的操作在每一台地区服务器执行。

检查网络和时间

1
2
3

getent hosts mender.example.com
curl -I https://mender.example.com/ui
timedatectl status

这一步验证三个前提：

• DNS 能解析总部域名；
• 出站 HTTPS 可用；
• 系统时间正确，TLS 和 Artifact 有效期判断不会出错。

地区服务器无需开放 Mender 入站端口。

安装Docker和Compose

按照 Docker 官方 Ubuntu 安装文档安装 Docker Engine 和 Compose 插件，然后验证：

1
2
3

docker version
docker compose version
sudo systemctl enable --now docker

Compose Update Module 会调用本机 Docker，因此 Docker 必须由 systemd 正常管理。

安装Mender Client

下面两种方式二选一。最快的方式是官方便利脚本，适合 PoC；先下载、审查，再执行：

1
2
3

curl -fLsS https://get.mender.io -o get-mender.sh
less get-mender.sh
sudo bash get-mender.sh mender-client4

只传入 mender-client4，可以避免便利脚本额外安装 Remote Terminal 和 Configure 插件。

生产环境更推荐显式配置官方 device-components APT 仓库并固定软件版本。Ubuntu 24.04 可以执行：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

sudo apt-get update
sudo apt-get install --assume-yes --no-install-recommends \
  apt-transport-https ca-certificates curl gnupg jq

curl -fsSL https://downloads.mender.io/repos/debian/gpg \
  | sudo tee /etc/apt/trusted.gpg.d/mender.asc >/dev/null

gpg --show-keys --with-fingerprint \
  /etc/apt/trusted.gpg.d/mender.asc

echo "deb [arch=$(dpkg --print-architecture)] https://downloads.mender.io/repos/device-components ubuntu/noble/stable main" \
  | sudo tee /etc/apt/sources.list.d/mender-device-components.list

sudo apt-get update
apt-cache madison mender-client4

从 apt-cache 输出中选定经过测试的版本。首次验证时可以安装仓库当前稳定版：

1

sudo apt-get install --assume-yes mender-client4

完成兼容性验证后，应在自动化安装清单中记录实际包版本，并通过 APT preference 或版本参数锁定，避免地区服务器在不同日期安装到不同客户端版本。

官方仓库签名密钥指纹应核对为：

1

E6C8 5734 5575 F921 8396 5662 2407 2B80 A1B2 9B00

安装后检查：

1
2
3
4

mender-update --version
mender-auth --version
mender-setup --help
systemctl status mender-authd mender-updated

mender-authd 负责设备认证和令牌，mender-updated 负责轮询、下载和安装更新。

配置连接总部

定义设备类型和服务器地址：

1
2
3
4
5
6

export DEVICE_TYPE='region-server-amd64'
export MENDER_SERVER_URL='https://mender.example.com'

sudo mender-setup \
  --device-type "$DEVICE_TYPE" \
  --server-url "$MENDER_SERVER_URL"

device-type 必须和后面生成 Artifact 时的兼容类型完全一致。不同 CPU 架构或部署形态应使用不同类型，例如：

1
2
3

region-server-amd64
region-server-arm64
factory-edge-amd64

生产环境不要使用 --demo-polling，它会产生比默认值更频繁的请求。

如果使用 Hosted Mender，不传 --server-url，而是从 Organization 设置中取得 Tenant Token：

1
2
3
4
5
6
7

export DEVICE_TYPE='region-server-amd64'
export TENANT_TOKEN='Replace-With-Tenant-Token'

sudo mender-setup \
  --device-type "$DEVICE_TYPE" \
  --hosted-mender \
  --tenant-token "$TENANT_TOKEN"

Tenant Token 能让新设备向组织申请接入，必须作为 Secret 管理，不能写入镜像、Git 或日志。Hosted 和自建 Server 两种配置方式同样是二选一。

配置轮询和证书

Mender Client 主配置位于：

1

/etc/mender/mender.conf

默认更新轮询周期是 1800 秒，Inventory 上报周期是 28800 秒。可以调整为：

1
2
3
4
5

{
  "ServerURL": "https://mender.example.com",
  "UpdatePollIntervalSeconds": 300,
  "InventoryPollIntervalSeconds": 3600
}

这只是最小结构示例。编辑时要保留 mender-setup 已写入的其他字段，不能直接覆盖整份配置。

• UpdatePollIntervalSeconds: 300：设备最多约 5 分钟发现新任务；
• InventoryPollIntervalSeconds: 3600：每小时上报一次地区和版本信息；
• 轮询越频繁，总部服务端压力越大。

如果总部使用公开可信 CA，客户端使用系统 CA 即可。如果使用企业私有 CA，应把 CA 证书放到客户端，例如：

1

/etc/mender/server.crt

然后在配置中增加：

1
2
3

{
  "ServerCertificate": "/etc/mender/server.crt"
}

不要在生产环境启用跳过 TLS 验证。

重新启动客户端：

1
2
3

sudo systemctl restart mender-authd mender-updated
sudo journalctl -u mender-authd -n 100 --no-pager
sudo journalctl -u mender-updated -n 100 --no-pager

在服务端接纳设备

客户端第一次运行时会生成自己的密钥：

1

/var/lib/mender/mender-agent.pem

然后向 Server 提交认证请求。在 Mender UI 中进入 Devices，找到 Pending 设备，核对设备 ID、公钥和主机信息后选择 Accept。

只有 Accepted 设备才能进入 Deployment。生产环境设备多时，可以使用预授权 API 或企业版 mTLS 自动接纳，但不能在没有身份校验的情况下自动接受任意设备。

第四阶段：上报地区Inventory并建立分组

Mender 会执行 /usr/share/mender/inventory 中所有以 mender-inventory- 开头的可执行文件，并把脚本标准输出解析为 Inventory。

在华东服务器创建：

1
2
3
4
5
6
7
8
9
10

sudo tee /usr/share/mender/inventory/mender-inventory-region >/dev/null <<'EOF'
#!/bin/sh
printf '%s\n' \
  'region=east-china' \
  'environment=production' \
  'site_id=site-001' \
  'service_type=factory-compose'
EOF

sudo chmod 700 /usr/share/mender/inventory/mender-inventory-region

手工检查脚本输出：

1

sudo /usr/share/mender/inventory/mender-inventory-region

这些属性用于搜索、筛选和分组，不用于唯一识别设备。site_id 也不应代替 Mender Device ID。

等待 Inventory 上报后，在 UI 中可以：

1. 建立静态组 pilot，手工加入试点服务器；
2. 建立静态组 production-east、production-south 等地区组；
3. 企业版可根据 region 和 environment 建立动态组。

静态组在创建 Deployment 时会固化设备列表。Deployment 创建后再向组里增加设备，不会把新设备自动加入正在执行的任务。

第五阶段：安装Docker Compose Update Module

只安装 Mender Client 还不能理解 docker-compose Artifact。需要在每台地区服务器安装对应 Update Module。

下载并安装模块

1
2
3
4
5
6
7
8
9

sudo apt-get update
sudo apt-get install --assume-yes git make m4

git clone --branch 1.0.0 --depth 1 \
  https://github.com/mendersoftware/mender-container-modules.git

cd mender-container-modules
make
sudo make install-docker-compose

这些命令的作用分别是：

• 下载固定版本的官方容器更新模块；
• make 将模板和公共 Shell 逻辑生成可执行模块；
• make install-docker-compose 安装到 Mender 的 Update Module 目录。

验证：

1
2

test -x /usr/share/mender/modules/v3/docker-compose
ls -l /usr/share/mender/modules/v3/docker-compose

Update Module 的文件名就是 Artifact payload type。客户端收到 docker-compose 类型负载时，会调用这个文件完成安装、提交或回滚。

规划Docker持久化目录

如果未来还要做 A/B 操作系统升级，Docker 镜像和业务数据不能留在会被整体替换的根分区。应把 Docker data-root 放到持久化数据分区，例如：

1
2
3

{
  "data-root": "/data/docker"
}

文件位置：

1

/etc/docker/daemon.json

修改后需要重启 Docker：

1
2

sudo systemctl restart docker
docker info | grep 'Docker Root Dir'

只做应用更新时也建议将数据库、上传文件、运行时配置和备份放在明确的持久化目录，不能依赖容器可写层。

第六阶段：在构建机安装Mender工具

下面的操作在总部 CI/CD Runner 或独立签名机构执行，不是在地区服务器执行。

配置工作站APT仓库

安装依赖并导入官方签名密钥：

1
2
3
4
5
6
7
8
9

sudo apt-get update
sudo apt-get install --assume-yes \
  apt-transport-https ca-certificates curl gnupg jq skopeo

curl -fsSL https://downloads.mender.io/repos/debian/gpg \
  | sudo tee /etc/apt/trusted.gpg.d/mender.asc >/dev/null

gpg --show-keys --with-fingerprint \
  /etc/apt/trusted.gpg.d/mender.asc

确认指纹为官方公布的：

1

E6C8 5734 5575 F921 8396 5662 2407 2B80 A1B2 9B00

Ubuntu 24.04 添加工作站工具源：

1
2
3
4
5

echo "deb [arch=$(dpkg --print-architecture)] https://downloads.mender.io/repos/workstation-tools ubuntu/noble/stable main" \
  | sudo tee /etc/apt/sources.list.d/mender-workstation-tools.list

sudo apt-get update
sudo apt-get install --assume-yes mender-artifact mender-cli

验证：

1
2
3

mender-artifact --version
mender-cli --version
skopeo --version

mender-artifact 处理 .mender 文件，mender-cli 与 Mender Server API 通信，skopeo 在不运行容器的情况下下载不同架构的镜像。

也可以直接使用官方 CI 工具镜像：

1

docker pull mendersoftware/mender-ci-tools:1.0.0

下载Compose Artifact生成器

1
2
3
4
5
6

sudo curl -fL \
  https://raw.githubusercontent.com/mendersoftware/mender-container-modules/1.0.0/src/gen_docker-compose \
  -o /usr/local/bin/gen_docker-compose

sudo chmod 755 /usr/local/bin/gen_docker-compose
gen_docker-compose --help

生成器负责解析 Compose、通过 Skopeo 下载镜像，再把 Compose 和镜像归档成 Mender Artifact。

第七阶段：准备业务Compose发布包

创建发布目录：

1
2

mkdir -p release/manifests release/output
cd release

示例 manifests/compose.yaml：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

services:
  frontend:
    image: registry.example.com/factory/frontend:2026.08.1
    restart: unless-stopped
    ports:
      - "8080:80"
    volumes:
      - /data/factory/runtime-config.json:/usr/share/nginx/html/runtime-config.json:ro
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://127.0.0.1/healthz"]
      interval: 10s
      timeout: 3s
      retries: 12

  backend:
    image: registry.example.com/factory/backend:2026.08.1
    restart: unless-stopped
    volumes:
      - /data/factory/backend-config.yaml:/app/config.yaml:ro
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://127.0.0.1:8080/health/ready"]
      interval: 10s
      timeout: 3s
      retries: 12

发布前需要完成以下应用改造：

• 镜像使用不可变版本标签，正式环境最好同时记录 digest；
• 地区差异配置通过 Volume 在运行时挂载；
• 前端提供 /healthz 和 /version.json；
• 后端提供 /health/live、/health/ready 和 /version；
• 数据库、用户上传和业务文件位于宿主持久化目录或外部服务；
• Compose 设置明确的 restart 和 healthcheck；
• 同一个镜像可以部署到所有地区，不能为每个地区重新构建。

如果私有 Registry 需要认证，先在构建机登录：

1

skopeo login registry.example.com

认证只用于构建机下载镜像。因为最终 Artifact 可以包含镜像归档，地区服务器不一定需要访问 Registry。

第八阶段：生成Mender Artifact

先检查镜像支持的架构：

1
2
3

gen_docker-compose \
  --list-architectures \
  --manifests-dir manifests

生成 amd64 Artifact：

1
2
3
4
5
6
7
8
9

gen_docker-compose \
  --artifact-name factory-release-2026.08.1 \
  --device-type region-server-amd64 \
  --architecture amd64 \
  --manifests-dir manifests \
  --project-name factory-service \
  --output-path output/factory-release-2026.08.1.mender \
  -- \
  --software-filesystem data-docker

参数作用如下：

生成器会得到两个主要负载：

• images.tar.gz：Compose 引用的容器镜像；
• manifests.tar：Compose 文件和相关清单。

读取 Artifact 信息：

1

mender-artifact read output/factory-release-2026.08.1.mender

重点检查：

• Artifact name；
• Compatible devices；
• payload type 是否为 docker-compose；
• 架构是否正确；
• Compose 项目名和软件文件系统是否正确。

第九阶段：签名并在客户端启用强制验签

TLS 保护传输过程，Artifact 签名则保证制品本身来自受信发布方。两者不能互相替代。

生成签名密钥

在独立签名机生成 RSA 3072 位密钥：

1
2
3
4
5
6
7

openssl genpkey \
  -algorithm RSA \
  -out private.key \
  -pkeyopt rsa_keygen_bits:3072

openssl rsa -in private.key -out public.key -pubout
chmod 600 private.key

• private.key：只保存在签名机、KMS、Vault 或 HSM，不能进入 Git 和地区服务器；
• public.key：部署到所有地区服务器，用于验证签名。

签名Artifact

1
2
3
4

mender-artifact sign \
  output/factory-release-2026.08.1.mender \
  -k private.key \
  -o output/factory-release-2026.08.1-signed.mender

验证：

1
2
3

mender-artifact validate \
  output/factory-release-2026.08.1-signed.mender \
  -k public.key

只有本地验证成功，才能上传到生产 Mender Server。

客户端安装验签公钥

在每台地区服务器执行：

1
2
3

sudo install -o root -g root -m 0644 \
  public.key \
  /etc/mender/artifact-verify-key.pem

在 /etc/mender/mender.conf 的现有 JSON 中加入：

1
2
3

{
  "ArtifactVerifyKey": "/etc/mender/artifact-verify-key.pem"
}

重新启动：

1

sudo systemctl restart mender-updated

一旦启用 ArtifactVerifyKey，客户端会拒绝未签名 Artifact 和签名不匹配的 Artifact。公钥轮换期间可以使用 ArtifactVerifyKeys 同时配置新旧公钥，确认全部设备获得新公钥后再删除旧公钥。

第十阶段：加入数据库备份、迁移和健康检查

Mender 能触发回滚，但它不知道数据库语义，也不会自动撤销 State Script 对数据库做出的修改。数据库升级必须自己设计。

State Script命名

Artifact State Script 使用以下格式：

1

<STATE_NAME>_<ACTION>_<ORDER>_<DESCRIPTION>

典型脚本：

1
2
3
4

ArtifactInstall_Enter_10_backup-database
ArtifactInstall_Leave_20_migrate-database
ArtifactCommit_Enter_10_health-check
ArtifactRollback_Enter_10_restore-database

脚本退出码：

脚本必须满足：

• 幂等，多次运行结果一致；
• 有明确超时；
• 诊断信息写到标准错误；
• 不把密码打印到日志；
• 备份放在持久化目录；
• 每次备份与 Deployment 或 release ID 关联；
• 实际验证备份可恢复，而不是只判断命令退出码。

健康检查示例

ArtifactCommit_Enter_10_health-check：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

#!/bin/sh
set -eu

attempt=1
while [ "$attempt" -le 30 ]; do
  if curl --fail --silent --show-error \
    http://127.0.0.1:8080/health/ready >/dev/null; then
    exit 0
  fi

  attempt=$((attempt + 1))
  sleep 10
done

echo 'backend readiness check failed after 300 seconds' >&2
exit 1

将健康检查放在 ArtifactCommit_Enter，可以在 Mender 正式提交版本之前阻止错误版本。返回 1 后，Mender 会执行 Update Module 回滚流程。

将脚本放进Artifact

给脚本执行权限：

1
2
3
4

chmod 755 scripts/ArtifactInstall_Enter_10_backup-database
chmod 755 scripts/ArtifactInstall_Leave_20_migrate-database
chmod 755 scripts/ArtifactCommit_Enter_10_health-check
chmod 755 scripts/ArtifactRollback_Enter_10_restore-database

生成 Artifact 时，将 --script 参数透传给 mender-artifact：

1
2
3
4
5
6
7
8
9
10
11
12
13

gen_docker-compose \
  --artifact-name factory-release-2026.08.1 \
  --device-type region-server-amd64 \
  --architecture amd64 \
  --manifests-dir manifests \
  --project-name factory-service \
  --output-path output/factory-release-2026.08.1.mender \
  -- \
  --software-filesystem data-docker \
  --script scripts/ArtifactInstall_Enter_10_backup-database \
  --script scripts/ArtifactInstall_Leave_20_migrate-database \
  --script scripts/ArtifactCommit_Enter_10_health-check \
  --script scripts/ArtifactRollback_Enter_10_restore-database

再次读取 Artifact，确认 State scripts 已被打包：

1

mender-artifact read output/factory-release-2026.08.1.mender

数据库迁移的准确执行时机必须根据业务确定。某些 Compose 安装流程会先启动新容器，因此更稳妥的方案可能是把迁移做成一次性 Compose service，并让业务服务在迁移成功后启动。不可逆迁移不应进入无人值守升级通道。

第十一步：上传Release

使用UI上传

进入 Mender UI：

1

Releases -> Upload

选择签名后的文件：

1

factory-release-2026.08.1-signed.mender

上传后展开 Artifact 信息，再次检查设备类型、版本、payload type 和签名状态。

使用mender-cli上传

在 Mender UI 的个人资料页面创建 Personal Access Token。Token 只显示一次，应存入 CI Secret。

1
2
3
4
5
6
7

export MENDER_SERVER_URL='https://mender.example.com'
export MENDER_PAT='Replace-With-Personal-Access-Token'

mender-cli artifacts \
  --server "$MENDER_SERVER_URL" \
  --token-value "$MENDER_PAT" \
  upload output/factory-release-2026.08.1-signed.mender

PAT 是长期凭据，权限继承创建它的用户。CI 应使用权限最小化的专用账号，并设置过期和轮换策略。

第十二步：创建灰度Deployment

推荐发布顺序：

1. 开发环境；
2. 测试地区；
3. pilot 试点组；
4. 一个低风险生产地区；
5. 10% 生产设备；
6. 全量地区。

在 Mender UI 创建 Deployment：

1. 选择 factory-release-2026.08.1 Release；
2. 目标选择 pilot 静态组；
3. 设置开始时间或立即开始；
4. 检查设备数量；
5. 创建 Deployment；
6. 观察下载、安装、成功和失败状态；
7. 试点观察期结束后，再创建下一批 Deployment。

    sequenceDiagram    participant CI as 总部CI/CD    participant MS as Mender Server    participant MC as 地区Mender Client    participant APP as Docker Compose服务    CI->>MS: 上传已签名Artifact    CI->>MS: 创建试点Deployment    MC->>MS: 按轮询周期检查更新    MS-->>MC: 返回Artifact和Deployment信息    MC->>MC: 下载并验证签名、设备类型    MC->>APP: 备份、安装Compose、执行迁移    MC->>APP: 调用健康检查    alt 健康检查成功        MC->>MS: 上报success    else 安装或检查失败        MC->>APP: 回滚Compose并恢复数据库        MC->>MS: 上报failure和日志    end  

Mender Server 不会让所有地区在同一秒执行。默认更新轮询为 30 分钟，本文示例改为 5 分钟，所以设备一般会在 5 分钟窗口内陆续开始。

中止和回滚不是同一操作

发现故障时，应先在 UI 或 API 中停止仍在进行的 Deployment，防止更多设备领取任务。中止任务不会自动把已经成功升级的设备降回旧版本。

需要人工回滚已经升级成功的设备时，应保留并重新发布上一版签名 Artifact，例如 factory-release-2026.07.4，再为受影响设备创建一个新的 Deployment。数据库只有在旧应用仍兼容当前 schema，或已执行经过验证的向下迁移、备份恢复后，才允许回退应用。

自动回滚只发生在当前安装流程尚未成功提交，并且 Update Module 或 State Script 报错的情况下。已经标记成功的 Deployment 不能依靠“中止”恢复旧版本。

第十三步：观察状态和排查失败

地区服务器日志

查看认证日志：

1

sudo journalctl -u mender-authd -n 200 --no-pager

查看更新日志：

1

sudo journalctl -u mender-updated -n 200 --no-pager

实时跟踪：

1

sudo journalctl -u mender-updated -f

失败 Deployment 的详细日志还会保存在：

1

/var/lib/mender/deployments.*.log

Mender 默认保留最近若干部署日志，并在失败时上传日志到服务端。

查看设备当前软件信息

1

sudo mender-update show-provides

应能看到当前 Artifact 和 Compose 软件版本。服务端 UI 中也可以从 Device 和 Release 页面交叉核对。

常见故障

设备一直Pending

检查：

• 管理员是否在 UI 接受设备；
• mender-authd 日志是否有 TLS 或认证错误；
• 设备时间是否正确；
• 是否错误复制了另一台服务器的 /var/lib/mender。

每台设备必须拥有独立身份。克隆服务器模板时，应在首次启动前清理模板中的 Mender 私钥和状态，再让每台机器自行生成。

certificate signed by unknown authority

表示客户端不信任总部 TLS 证书。使用公开 CA 时更新系统 ca-certificates；使用私有 CA 时，将正确 CA 放入 /etc/mender/server.crt 并配置 ServerCertificate。

不能通过关闭证书验证掩盖问题。

Artifact显示noartifact

通常是 Artifact 的 compatible device type 与客户端 Device Type 不一致。检查：

1
2

cat /var/lib/mender/device_type
mender-artifact read release.mender

两边的值必须完全相同。

签名验证失败

检查：

• 上传的是签名后文件，不是原始文件；
• 客户端配置指向正确公钥；
• 签名后没有再次修改 Artifact；
• 公钥轮换期间新旧密钥配置是否完整。

Compose安装失败

检查：

1
2
3
4
5

docker compose version
docker info
df -h
df -i
ls -l /usr/share/mender/modules/v3/docker-compose

常见原因包括磁盘不足、镜像架构错误、端口冲突、Volume 路径不存在、Compose 语法错误和健康检查命令缺失。

版本出现_INCONSISTENT

这表示上一次部署失败，并且回滚失败或 Update Module 无法完成回滚。此时不能继续自动发布，应先读取设备 Deployment 日志，确认容器、配置和数据库实际处于哪个版本。

可选：每个地区部署Mender Gateway

当一个地区有很多设备，或者只有地区出口服务器能访问总部时，可以部署 Mender Gateway。

    flowchart LR    MS[总部Mender Server] <-->|HTTPS| GW[地区Mender Gateway]    GW -->|局域网HTTPS| D1[服务器1]    GW -->|局域网HTTPS| D2[服务器2]    GW -->|局域网HTTPS| D3[服务器3]    GW --> CACHE[(地区Artifact缓存)]  

Gateway 可以：

• 代理设备到总部的 Mender API 请求；
• 把 Artifact 下载地址替换为地区网关地址；
• 第一次下载后缓存在本地，后续设备复用；
• 为网关后的设备统一增加 region 等 Inventory；
• 配合 mTLS 自动接纳持有有效客户端证书的设备。

Mender Gateway 属于 Enterprise 能力。它不是一套独立地区 Mender Server，也不会在总部上传 Release 后立即主动同步全部 Artifact；缓存通常在设备实际请求时产生。

示例 /etc/mender/mender-gateway.conf：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

{
  "HTTPS": {
    "Enabled": true,
    "Listen": ":443",
    "MinimumTLSVersion": "1.2",
    "ServerCertificate": "/var/lib/mender/server-cert.pem",
    "ServerKey": "/var/lib/mender/server-pkey.pem"
  },
  "Features": {
    "ArtifactsProxy": {
      "Enabled": true,
      "GatewayURL": "https://mender-gateway-east.example.com",
      "DomainWhitelist": ["s3.example.com"],
      "ArtifactsCache": {
        "Enabled": true,
        "Path": "/var/cache/mender-gateway",
        "SignatureSecret": "Replace-With-Random-Base64-Secret",
        "LinkExpireDuration": "30m"
      }
    },
    "DeviceSystem": {
      "Enabled": true,
      "SystemID": "east-region-gateway",
      "DefaultInventory": [
        {
          "Name": "region",
          "Value": "east-china"
        }
      ]
    }
  },
  "UpstreamServer": {
    "URL": "https://mender.example.com",
    "CACertificate": "/etc/ssl/certs/ca-certificates.crt",
    "InsecureSkipVerify": false
  }
}

部署时还要完成：

• 从企业下载区取得与系统匹配的 mender-gateway Debian 包；
• 为 Gateway 配置受信 TLS 证书；
• 为缓存准备独立磁盘或 Volume；
• 将 DomainWhitelist 限制为真实 Artifact 存储域名；
• 把地区设备 ServerURL 指向 Gateway；
• Gateway 2.2.0 或更新版本可启用 Prometheus /metrics，应只监听 127.0.0.1:9102 或受信管理网；
• 监控缓存磁盘、请求错误率和到总部的连通性。

如果每个地区只有一台服务器并且网络稳定，Gateway 的收益很低，可以先不部署。

如果每个地区必须有独立Mender Server

有些企业要求地区断开总部后仍能独立创建发布。此时可以在每个地区部署完整 Mender Server，但这已经是多套独立控制面。

需要额外开发或建设：

• 总部 Artifact 向各地区对象存储复制；
• Release 元数据同步；
• 地区 Deployment 创建和状态汇总；
• API Token、账号和权限管理；
• 失败补偿和重复同步幂等；
• 总部与地区版本冲突处理；
• 断网期间操作审计合并。

Mender Gateway 不能替代这套联邦控制逻辑。除非有明确的地区自治或长期断网要求，否则优先使用一个中心 Mender Server 加多个 Gateway。

操作系统A/B升级与Compose升级的区别

本文安装 Debian 包的方式只能直接获得应用更新能力，不能自动获得完整操作系统回滚。

A/B rootfs 需要：

• 两个根文件系统分区；
• 持久化数据分区；
• GRUB 或 U-Boot 集成；
• Mender 化的 Debian/Yocto 镜像；
• 启动成功确认和 boot counter；
• 重新刷写或迁移现有服务器磁盘布局。

对于已经运行 Docker Compose 的普通服务器，建议第一期只做应用升级；操作系统补丁继续使用现有的系统运维工具。等应用发布链路稳定后，再单独评估 rootfs OTA。

哪些是安装配置，哪些必须自己开发

使用 Mender 的主要价值，是省掉设备注册、轮询协议、制品存储、部署状态机、基础重试和管理 UI。真正需要自己开发的部分集中在业务健康、Compose 约束、数据库和企业发布流程。

生产上线清单

正式启用无人值守更新前，至少确认：

• Mender Server 使用固定 Chart 和镜像版本；
• MongoDB、Redis、NATS 和对象存储有明确维护责任；
• MongoDB 与 Artifact 存储已经完成恢复演练；
• 总部入口只提供 HTTPS，证书续期有监控；
• 每台地区服务器身份唯一；
• 地区服务器只需要出站 HTTPS；
• Artifact 强制签名验证；
• 私钥不在构建机工作目录、Git 或地区服务器；
• Device Type、架构和 Compose 项目名有统一规范；
• 镜像使用不可变版本并保留 digest；
• 前端、后端和数据库 schema 使用同一个 releaseId；
• 配置、数据库和用户数据位于持久化目录；
• 数据库备份和恢复在真实测试库演练通过；
• State Script 幂等并有超时；
• 健康检查失败能触发 Compose 和数据库回退；
• 保留至少 N-1 版本所需制品和数据恢复点；
• 发布按试点、灰度、全量执行；
• 有人工暂停、终止、回滚和现场恢复手册；
• 日志中不包含密码、私钥、Token 和业务敏感数据。

总结

使用 Mender 实现中心发布、多地区服务器升级，最合理的职责划分是：

1. 总部 Mender Server 管理设备、Release、Deployment 和状态；
2. 总部 CI/CD 构建 Compose、打包镜像、生成并签名 Artifact；
3. 地区 Mender Client 主动轮询、下载、验签和调用 Update Module；
4. 官方 Compose Update Module 负责容器和 Compose 安装流程；
5. 企业自己负责业务健康检查、数据库备份、迁移和恢复；
6. 设备较多或出口受限的地区使用 Mender Gateway 做代理和缓存；
7. 只有明确要求地区自治时，才部署多套 Mender Server 并开发同步平台。

Mender 不是把所有升级问题自动解决，而是提供一套可靠的通用分发和设备状态基础。把 Artifact 验签、灰度发布、业务健康和数据库恢复四部分同时做好，才能把“能够远程更新”提升为“可以在生产环境无人值守更新”。

参考资料

• Mender官方文档
• Mender Server评估环境
• Kubernetes生产部署
• Mender Server Helm安装
• Mender Client Debian安装
• Mender设备端组件下载
• Mender工作站工具下载
• Docker Compose Artifact创建
• Mender Artifact签名与验证
• Mender State Scripts
• Mender Inventory
• Mender Deployment
• Mender Gateway
• Mender Server备份与恢复
• Mender Server API与CLI
• Mender支持版本