企业官网建设流程全解析

• 日志分析
• 运维观测

本文基于 graylog2-server 仓库data-node/migration/目录下的 Manual Migration Guide 及其配套脚本与配置，完整讲解如何把一个既有 OpenSearch 2.x 或 1.3.x 集群（以及 Elasticsearch 7.10 集群）手动迁移为 Graylog DataNode 集群。读者将掌握：证书生成与无证书环境的适配方法、OpenSearch Security 从"用户/角色模型"切换为"JWT 认证模型"的关键步骤、securityadmin.sh数据重载操作，以及通过 Preflight UI 完成 DataNode 证书配发的完整流程。文中所有命令、配置片段均可在仓库中对应的 docker-compose.yml、es710-docker-compose.yml、cert.sh、custom-opensearch.yml 等文件中找到原始出处。

文档性质与适用前提

仓库中的这份 Manual-Migration.md 明确标注为preliminary（初稿/前置验证文档），其定位是为当前代码库找出"哪些修改是必须的"提供一个最小化基础，并用于研究、测试可能的用户体验改进、找出实际能力边界。它来自开发者自建 Docker 环境的实践，而非官方承诺的生产迁移路径。

因此请注意三条重要前提：

• 生产环境不可直接照搬：文档原文强调"如果你试图用这份指南对真实生产系统做手动迁移，所有关于证书等的准备工作大概率与你的使用场景不匹配，请自行调整"。本文所有密码、证书 DN、hostname 均来自开发环境示例。
• Docker 复现环境：整个流程基于 Docker 编排以保证步骤可重复，真实安装（如 OS 包安装）步骤必然存在差异，但迁移逻辑（数据目录、安全配置切换、认证机制）是通用的。
• 可能有用武之地：文档提到这些步骤未来可能用于 PSO（专业服务）或支持团队手动迁移、修复迁移中发生的问题，也可作为运维排障时的参考手册。

迁移前必须注意的事项

文档列出了一份"未充分测试但必须留神"的清单，核心是保持原有元数据与集群拓扑的一致性：

• 保持 hostname 不变：DataNode 节点继续沿用原 OpenSearch 节点的 hostname（示例中 DataNode 的hostname直接设为opensearch1/2/3）。
• 保持 cluster name 不变：示例中cluster.name=datanode-cluster在整个迁移过程始终保持一致。

原因是 OpenSearch 数据目录中已经写入的集群元数据（cluster state、security index 等）与节点名、集群名强绑定。一旦改动，可能与数据目录中的既有元数据产生冲突（例如.opendistro_security索引、nodes 信息），轻则启动失败，重则损坏数据。文档还特别警告：在很多情况下，遗漏一步或出现一个错误，你除了完全重来之外别无选择，而生产环境可能不具备"重来"的条件——所以务必先做完整备份。

另外文档附带一条 macOS 开发提示：如果在 macOS 上测试/开发时遇到为 Docker 设置vm.max_map_count失败的情况，且正在运行最新版 Docker，很可能是最新 Docker 版本与 macOS Sonoma 不兼容，唯一解决办法是降级 Docker 版本。

迁移目录里的配套文件清单

data-node/migration/目录下除指南外还有 7 个配套文件，迁移全程都围绕它们展开：

环境准备：本地镜像与无证书集群的裁剪

本地构建镜像

开发阶段可使用create-docker-images.sh创建/引入本地生成的 Graylog 或 DataNode Docker 镜像，便于在改动代码后快速验证迁移流程。

不使用证书时的裁剪方法

如果目标 OpenSearch 集群不使用证书（无 TLS），就不需要生成证书，需要从 docker-compose.yml 中删除三处内容：

1. 从每个 OpenSearch 服务（opensearch1/2/3）的 volumes 中删除证书相关挂载行（?按服务替换为 1–3）：

- "./root-ca.pem:/usr/share/opensearch/config/root-ca.pem" - "./node?.pem:/usr/share/opensearch/config/node.pem" - "./node?-key.pem:/usr/share/opensearch/config/node-key.pem" - "./admin.pem:/usr/share/opensearch/config/admin.pem" - "./admin-key.pem:/usr/share/opensearch/config/admin-key.pem" - "./keystore.jks:/usr/share/opensearch/config/keystore.jks" - "./custom-opensearch.yml:/usr/share/opensearch/config/opensearch.yml"

2. 从 graylog 服务 environment 中删除证书配置：

GRAYLOG_CA_KEYSTORE_FILE: "/usr/share/graylog/data/keystore.jks" GRAYLOG_CA_PASSWORD: "password"

3. 从 graylog 服务 volumes 中删除：

- "./keystore.jks:/usr/share/graylog/data/keystore.jks"

准备env文件

修改env文件，内容与仓库常规 docker compose 示例一致，其中提供GRAYLOG_PASSWORD_SECRET（密码密钥）与GRAYLOG_ROOT_PASSWORD_SHA2（admin 密码的 SHA-256）两个变量，并重命名为.env。docker-compose.yml 中通过${GRAYLOG_PASSWORD_SECRET:?...}与${GRAYLOG_ROOT_PASSWORD_SHA2:?...}引用它们，缺失时会直接报错提示。同时可选的${DATANODE_IMAGE}/${GRAYLOG_IMAGE}变量用于覆盖默认的graylog/graylog-datanode:5.2.0与graylog/graylog:5.2.0镜像。

生成证书（使用证书的场景）

运行 cert.sh 为 OpenSearch 集群生成证书，证书相关口令统一使用password，以与其他脚本/文件保持一致。脚本执行的内容包括：

• 生成 2048 位 RSA 根 CA（root-ca-key.pem/root-ca.pem，有效期 730 天，subject 为/C=CA/ST=ONTARIO/L=TORONTO/O=ORG/OU=UNIT/CN=root）；
• 生成 admin 证书（admin-key.pem/admin.pem，CN=A）；
• 依次为opensearch1、opensearch2、opensearch3生成节点证书，每个证书的 subjectAltName 为对应节点 DNS 名；
• 清理中间文件（csr、临时 key、ext）；
• 用keytool -import -trustcacerts将各节点证书、admin 证书与根 CA 导入keystore.jks（别名为opensearch1/2/3、admin、root）。

这些证书随后被 custom-opensearch.yml 引用：该文件配置了 transport/http 层的 PEM 证书路径（node.pem、node-key.pem、root-ca.pem）、JKS truststore（keystore.jks，口令password），以及plugins.security.authcz.admin_dn（CN=A,OU=UNIT,O=ORG,L=TORONTO,ST=ONTARIO,C=CA）和plugins.security.nodes_dn（三个节点的 CN）等安全配置。

准备 DataNode 安全配置：把密码密钥写入 JWT 配置

datanode-security-config.yml 是 DataNode 使用的 OpenSearch Security 配置，核心差异在于它启用了JWT 认证域（jwt_auth_domain）：http_enabled: true、transport_enabled: true、order: 0，认证方式为type: jwt（非挑战式），并设置了roles_key: "os_roles"。

迁移前需要把GRAYLOG_PASSWORD_SECRET以 base64 形式填入该文件第 131 行的signing_key字段。文档给出的转换方法：

echo "The password secret you chose" | base64

将输出粘贴到datanode-security-config.yml中signing_key:的引号内（替换默认占位"base64 encoded GRAYLOG_PASSWORD_SECRET from .env file"）。该 HMAC 密钥正是后续 Graylog 签发、OpenSearch 校验 JWT 的共同秘密——从源码看，DataNode 侧由 DatanodeJwtAuthTokenProvider 负责生成带os_roles角色的 JWT，而 OpenSearch Security 插件以相同密钥验签，二者必须严格一致。

从 OpenSearch 2.x / 1.3.x 迁移的完整步骤

以下步骤基于 docker-compose.yml：单 MongoDB（mongo:7.0）+ 单 Graylog 节点 + 三节点 OpenSearch（opensearchproject/opensearch:2.10.0）。全程可通过docker compose down -v加还原文件修改来随时重来。

步骤 1：OpenSearch 1.3.x 的镜像替换

若源集群是 OpenSearch 1.3.x，只需把三个服务的镜像2.10.0替换为1.3.1即可（对应 es710-docker-compose.yml 中的 OpenSearch 部分写法）。

步骤 2：创建容器并启动原始集群

docker compose create docker compose up -d mongodb opensearch1 opensearch2 opensearch3 graylog1

等集群就绪后，在 Graylog Web 界面创建一个 Input，摄入一些数据（例如发送测试 GELF/syslog 日志），验证旧集群工作正常。

步骤 3：停止服务并切换 OpenSearch 安全配置

docker compose stop graylog1 opensearch1 opensearch2 opensearch3

修改docker-compose.yml中三个 OpenSearch 服务的 security config 挂载：把注释切换到datanode-security-config.yml，即从"用户/角色模型"切换到"JWT 认证模型"：

- "./opensearch-security-config.yml:/usr/share/opensearch/config/opensearch-security/config.yml" # - "./datanode-security-config.yml:/usr/share/opensearch/config/opensearch-security/config.yml"

改为：

# - "./opensearch-security-config.yml:/usr/share/opensearch/config/opensearch-security/config.yml" - "./datanode-security-config.yml:/usr/share/opensearch/config/opensearch-security/config.yml"

对比两个安全配置文件可以看清差异：opensearch-security-config.yml 中basic_internal_auth_domain为http_enabled: true（HTTP Basic + 内部用户库），而 JWT 域处于禁用状态；datanode-security-config.yml 则反过来禁用了 basic 域、启用 JWT 域。这正是"从用户/角色模型切到 JWT 认证"的本质。

步骤 4：重启 OpenSearch 并重载安全数据

docker compose create opensearch1 opensearch2 opensearch3 docker compose up -d opensearch1 opensearch2 opensearch3

通过日志或curl确认 OpenSearch 已恢复。然后用docker ps取得任一节点容器 ID，进入容器执行 OpenSearch Security 的securityadmin.sh重载安全配置：

docker exec -it <ID> bash cd /usr/share/opensearch/plugins/opensearch-security/tools ./securityadmin.sh -f /usr/share/opensearch/config/opensearch-security/config.yml -icl -h opensearch1 -nhnv -cacert ../../../config/root-ca.pem -cert ../../../config/admin.pem -key ../../../config/admin-key.pem

命令参数含义：-f指定要加载的配置文件；-icl（initialize cluster）在集群首次初始化时也允许执行；-h指定目标节点；-nhnv关闭 hostname 校验；-cacert/-cert/-key提供 admin 证书链。

这一步是整个迁移的关键：它确保 OpenSearch 数据目录（包含 security indices 等）在把数据目录挂载给 DataNode 之前，就已写入 JWT 认证数据。否则后续 DataNode 接管数据目录时，安全索引中的认证配置仍是旧模型，无法用 JWT 通信。

步骤 5：停止 OpenSearch，修改 Graylog 为 Preflight 模式

docker compose stop opensearch1 opensearch2 opensearch3

修改 graylog 服务的 environment：注释掉连接 OpenSearch 的配置与证书配置，开启 Preflight Web UI：

# GRAYLOG_CA_KEYSTORE_FILE: "/usr/share/graylog/data/keystore.jks" # GRAYLOG_CA_PASSWORD: "password" # GRAYLOG_ELASTICSEARCH_HOSTS: "https://admin:admin@opensearch1:9200,https://admin:admin@opensearch2:9200,https://admin:admin@opensearch3:9200" GRAYLOG_ENABLE_PREFLIGHT_WEB: "true"

步骤 6：启动 DataNode 并通过 Preflight UI 配发证书

docker compose create graylog1 docker compose up -d graylog1 datanode1 datanode2 datanode3

用docker compose logs -f graylog1查看日志末尾输出的认证信息，然后登录http://localhost:9000的Preflight UI。在界面中为三个 DataNode 配发（provision）证书，配发成功后 DataNode 会启动并进入 green 状态，随后继续（Resume）Graylog 的启动流程。文档提示"此时暂时不应发生任何额外动作——这个问题会在开发中很快被处理"，随即执行docker compose stop graylog1。

值得说明的是，DataNode 的证书生命周期管理在源码中有完整实现：从preflight包下的 DatanodeCertReceiver、DatanodeKeystoreInitService，到定期的 DataNodeCertRenewalPeriodical，再到 REST 层的 CertificatesController，构成"签发—下发—续期"的完整链路，迁移时 DataNode 与 Graylog 之间的 TLS 即依赖这套机制。

步骤 7：关闭 Preflight，恢复 Graylog 正常启动

在docker-compose.yml中注释掉 Preflight 开关：

# GRAYLOG_ENABLE_PREFLIGHT_WEB: "true"

然后：

docker compose create graylog1 docker compose up -d graylog1

此时即可用常规账号登录http://localhost:9000的 Graylog 界面，此时后台已是DataNode 集群（三个 DataNode 服务各自挂载了原 OpenSearch 的数据卷，见 compose 中opensearch-data-0X:/var/lib/graylog-datanode/opensearch/data的映射关系），原有数据与索引继续可用。

从 Elasticsearch 7.10 迁移：必须经由 OpenSearch 中转

Elasticsearch 7.10 的迁移需要额外一步，因为ES 7.10 原生不支持 JWT 认证。因此不能直接对 ES 数据目录做安全配置切换，必须先把它变成 OpenSearch，再走上述 OpenSearch 迁移流程。

参考 es710-docker-compose.yml，它演示了完整链路：

1. Elasticsearch 阶段：elasticsearch1/2/3使用docker.elastic.co/elasticsearch/elasticsearch-oss:7.10.2镜像，注意其hostname与node.name已经被设为opensearch1/2/3、cluster.name设为datanode-cluster（文档说明：示例中为了省事改了名字，真实场景应反过来——把 elasticsearch 的名字贯穿整个迁移流程带到 DataNode，即遵循"保持 hostname 与 cluster name 不变"的原则）。ES 服务直接挂载opensearch-data-0X数据卷，且此阶段不挂载任何证书。

2. 启动并灌数据：

docker compose up -d elasticsearch1 elasticsearch2 elasticsearch3 # ... 写入测试数据 ... docker compose stop elasticsearch1 elasticsearch2 elasticsearch3

3. 原地替换为 OpenSearch：opensearch1/2/3（opensearchproject/opensearch:1.3.1）指向同一批数据目录：

docker compose up -d opensearch1 opensearch2 opensearch3

该 compose 文件中 OpenSearch 服务已挂载datanode-security-config.yml（JWT 安全配置）、custom-opensearch.yml与各节点证书，也就是说 OpenSearch 起来时就直接携带 JWT 配置；启动前务必确认已把正确的 base64 编码 secret 填入了安全配置文件。

4. 执行securityadmin.sh重载（命令与上节一致），然后完全沿用 OpenSearch 1.3.x 迁移的后续步骤（Preflight UI、DataNode 证书配发、关闭 Preflight、恢复 Graylog）。

注意：ES 阶段不含证书，证书是在启动 OpenSearch 集群时通过cert.sh等生成的。ES 数据（Lucene 索引格式）能被 OpenSearch 1.x 直接读取，这是"原地替换"可行的基础。

从源码理解迁移后的运行机制

迁移完成后，DataNode 接管了原搜索集群的全部职责。仓库中data-node/src/main/java/org/graylog/datanode/下的实现可帮助深入理解这套机制：

• 进程管理：OpensearchProcessImpl 与 OpensearchProcessService 负责拉起、监控底层 OpenSearch 进程；OpensearchStateMachine 管理节点的生命周期状态（start/stop/cert-received 等）。
• 安全与认证：JwtTokenAuthFilter 对 DataNode API 请求做 JWT 校验，DatanodeJwtAuthTokenProvider 为 OpenSearch 生成携带os_roles的令牌——这正是迁移配置中signing_key/roles_key的运行时对应物。
• 数据目录兼容性：迁移的本质风险在于数据目录。filesystem/下的 OpensearchDataDirCompatibilityService 及配套测试 OpensearchDataDirCompatibilityServiceTest、OpensearchDataDirCompatibilityCheck 会在 DataNode 启动前检查既有数据目录的索引版本与格式兼容性（如 Lucene 版本、是否包含 DataNode 所需目录结构），支撑"原 OpenSearch/ES 数据目录直接交给 DataNode"这一迁移核心假设。
• 集成验证：data-node/src/test/java/org/graylog/datanode/integration/下的 DatanodeClusterIT、DatanodeSecuritySetupIT 等集成测试覆盖了集群组建与安全配置场景，是理解 DataNode 集群行为的参考实现。

迁移清单速查

最终整理成可直接对照执行的操作顺序：

1. 备份全部数据卷（MongoDB、OpenSearch 数据目录、Graylog 数据与 journal），核对.env中GRAYLOG_PASSWORD_SECRET与GRAYLOG_ROOT_PASSWORD_SHA2；
2. 运行 cert.sh 生成证书（口令password），或按上文裁剪无证书配置；将GRAYLOG_PASSWORD_SECRETbase64 后写入 datanode-security-config.yml 的signing_key；
3. docker compose create并up -d mongodb opensearch1 opensearch2 opensearch3 graylog1，建 Input、灌数据；
4. docker compose stop graylog1 opensearch1 opensearch2 opensearch3，切换安全配置挂载为datanode-security-config.yml；
5. 重启 OpenSearch，容器内执行securityadmin.sh重载 JWT 安全数据；docker compose stopOpenSearch；
6. 修改 graylog 环境变量（注释旧连接、开启GRAYLOG_ENABLE_PREFLIGHT_WEB），up -d graylog1 datanode1 datanode2 datanode3；
7. 登录http://localhost:9000Preflight UI，配发 DataNode 证书、等待节点 green、Resume Graylog，然后停 graylog；
8. 注释 Preflight 开关，重新create+up -d graylog1，用常规账号登录验证；
9. Elasticsearch 7.10 场景：在步骤 3 前先按 es710-docker-compose.yml 用 ES 7.10 灌数据，再原地换为 OpenSearch 1.3.1 接管同一数据目录，之后并入步骤 4 起的流程。

再次强调：这是初步（preliminary）迁移指南，目标是为开发、研究与支持场景提供可复现的最小基准。生产环境迁移请以官方发布文档为准，并务必在完整备份、隔离验证之后再进行。

• 日志分析
• 运维观测