Skip to Content
工作文档周报2025年度总结2025年12月01日

2025年12月01日

本周工作计划与执行完成进度

中心服务平台 - 新增功能

  • 目标: 完善运维相关功能
  • 进度: 已完成 65% | 计划完成 100%。受多个非计划内事务的影响。（🟢 未开始 | 🟡 进行中 | ⚠️ 部分完成 | ✅ 已完成 | 📌 已验证）
    • ✅ 中心服务器数据库备份功能，实现通过 Web 界面手动触发数据库备份，并支持每日凌晨 1 点自动执行定时备份任务。为避免磁盘空间过度占用，当备份文件数量超过 30 个时，系统将自动删除最旧的备份文件，确保备份数据的时效性与存储合理性。
      • ✅ 📌 后端开发：
        • ✅ es-center-server-agent（Rust + axum 等生态组件，编译为的原生服务程序）
          • ✅ 完成跨 Docker 容器执行数据备份命令的技术调研，确定安全、可靠的执行方案。
          • ✅ 搭建 es-center-server-agent 项目框架，集成 Rust 生态主流库：axum（Web 框架）、tokio（异步运行时）、serde / serde_json（序列化）、color-eyre（错误处理）、ring（加密）、ulid（唯一标识生成）、flurry（并发哈希表）及 redis（缓存支持）。
          • ✅ 实现配置管理模块，支持加载 .env（生产环境）与 .env.development（开发环境）配置文件，开发环境配置可覆盖生产环境配置，便于多环境适配。
          • ✅ 基于 OpenAPI 3.0 规范（通过 swagger-ui 与自动生成的 openapi.json），完成端到端接口链路开发：涵盖 API 层、服务层、仓库层，最终执行底层 SQL 查询并统一封装为标准化 JSON 响应格式。
          • ✅ 实现数据库自动备份机制：每小时轮询检查当日备份是否已完成；若未完成，则触发备份流程。备份成功后，自动清理超出 30 个的最旧文件，确保备份的时效性与存储合理性。
          • ✅ 移除 /agent-api/v1/user 测试接口，避免暴露非生产用途接口。
          • ✅ 新增三项核心接口：手动触发数据库备份、获取备份文件列表及下载指定备份文件。其中，手动触发数据库备份接口已实现备份文件数量管控机制，限制手动类别最多保留 50 个备份文件，超出上限时自动清理最旧的备份文件，确保存储资源合理使用。
          • ✅ 为所有对外接口实现安全防护机制，防止未授权访问与恶意调用。
      • ✅ 📌 前端开发：
        • ✅ es-secure-encoder（Rust + wasm-bindgen 等生态组件，编译为 WASM 的前端模块）
          • ✅ 开发 Web 端 Agent API Token 生成所用的 WASM 模块，通过将加密逻辑编译至二进制字节码，提升安全性，有效抵御反编译风险，保护核心算法。
        • ✅ es-center-server-web-app（React + shadcn-ui 等生态组件，纯前端程序）
          • ✅ 集成新版本的 es-secure-encoder wasm 模块，实现 Agent API Token 生成
          • ✅ 手动触发数据库备份功能界面
          • ✅ 数据库备份文件列表功能界面，支持下载备份文件，其中备份文件下载权限限定为超级管理员和租户管理员(受后端权限策略的控制)
      • ✅ 📌 后端开发：
        • ✅ es-center-server-main-service (Java + spring boot 等生态组件，编译为的微服务程序)
          • ✅ 新功能的权限策略维护，明确数据库备份及备份文件下载操作仅对超级管理员开放(受后端权限策略的控制)。
      • ✅ 📌 安装与更新程序集成, center-server-install-app（Python + click 等生态组件，编译为的原生工具程序）
        • ✅ 将 es-center-server-agent 集成至现有安装与更新程序，实现一键部署并注册为 Linux 系统服务，提升运维自动化水平。
        • ✅ 部署至 zxs-ca 服务器，对更新程序进行测试，确保功能正常运行。
    • ✅ 提供设备通用上传接口，并制定上传协议，确保日志完整上传至服务器，便于客户分析问题、排查原因。
      • ✅ 后端开发：
        • ✅ es-center-server-main-service (Java + spring boot 等生态组件，编译为的微服务程序)
          • ✅ 制定设备通用上传接口通信协议（通过传入 type 字段进行归类区分），并输出标准化接口文档，供设备端开发人员对接使用。涉及接口实现安全防护机制，防止未授权访问与恶意调用。
          • ✅ 完成设备通用上传接口的开发与实现。
          • ✅ 新功能的权限策略维护，日志下载权限限定为超级管理员和租户管理员。
          • ✅ OpenAPI 开发：获取已上传的第一层文件夹列表，提取已上传文件夹名称为设备编号列表
          • ✅ OpenAPI 开发：根据指定的设备编号（对应第一级目录）和类别（对应第二级目录），第三级目录中的文件列表包含类别、文件大小及文件名等字段。
        • ✅ es-center-server-device-service (Java + spring boot 等生态组件，编译为的微服务程序)
          • ✅ 通知设备端上传文件的 MQTT 消息：设备端收到消息后，根据消息内容执行文件上传操作。例如，通过 type 字段指定需上传的文件类型，如日志文件、数据库文件、配置文件等。
      • ✅ 前端开发：
        • ✅ es-center-server-web-app（React + shadcn-ui 等生态组件，纯前端程序）
          • ✅ 开发在设备通用已上传文件列表界面：支持按设备编号筛选功能。支持具备权限的用户下载文件，其中文件下载权限限定为超级管理员和租户管理员(受后端权限策略的控制)。
        • ✅ 其它
          • ✅ 部署至 zxs-cs 测试环境，用于支撑与设备端的联调；结合日志记录与反馈信息，持续优化接口性能与功能完整性。

中心服务平台 - 轻量化分布式过渡阶段改造

  • 目标: 控制变更范围，降低引入风险，实现面向客户可用的初步功能体验。
  • 进度: 已完成 25% | 计划完成 30%（🟢 未开始 | 🟡 进行中 | ⚠️ 部分完成 | ✅ 已完成 | 📌 已验证）
    • ✅ 手机号注册的用户名生成策略：针对通过手机号注册的用户，系统采用格式化规则自动生成用户名，格式为 p-${手机号}。该方案利用手机号的全局唯一性，并结合用户名字符限制要求，有效避免了用户名冲突问题。相较原有的随机生成策略，在分布式部署环境下，显著降低了因多节点并发注册导致的单点登录跳转失败风险。
    • ✅ 邮箱注册的用户名生成策略：对于通过邮箱注册的用户，系统采用格式化规则自动生成用户名，格式为 ${邮箱名}。该方案利用邮箱名的全局唯一性，并结合用户名字符限制要求，有效避免了用户名冲突问题。相较原有的随机生成策略，在分布式部署环境下，显著降低了因多节点并发注册导致的单点登录跳转失败风险。
    • 🟢 用户注册用户名规范：为保障系统的统一性与安全性，用户注册时的用户名仅允许包含字母、数字和下划线，禁止使用特殊字符及空格。该限制旨在避免因手机号或邮箱自动生成用户名时可能引发的命名冲突问题。
      • ✅ 前端部分交由曹溯川处理：员工及租户创建或修改时，会有登录帐号（用户）的用户名验证逻辑加固，确保用户名符合规范。
      • ✅ 其它部分由我处理
    • ✅ 支持在设备及采集服务器维护界面配置设备所属的节点云服务器，涵盖数据库设计、接口开发、前端及权限控制等各个方面的处理。
      • ✅ 前端部分交由曹溯川处理
      • ✅ 其它部分由我处理
    • ✅ 设备及采集服务器修改，当租户为 default（个人设备库存 ）时，需保持同编号设备在其他租户下的配置一致；动作：以 deviceNo 为键，批量更新非 default 租户的同编号设备配置，防止多租户场景下配置漂移；字段：云服务域名、Janus 编号、STUN/TURN 服务与认证信息。
    • 🟡 集成 Nacos 实现全球节点服务器的配置统一管理，比如：支持设备归属节点的动态配置分发；Super-Token 业务提供可靠的配置数据支撑。
      • 🟡 因工期紧张，暂采用简化方案，仅在主节点主机部署单实例 Nacos；后续将迭代为稳定架构。
    • 🟡 改造原有无状态 JWT Token 的加解密机制，集成 Nacos 同步的盐值配置。通过传递包含时效性信息的统一认证头（Super-Token），实现跨节点服务器的单点登录功能，完成 Super-Token 方案的落地。
    • 🟢 手机注册成功，根据手机传参的定位信息，计算出以后它应该与那个服务器交互（就近原则），返回信息中增加服务器地址信息。
    • 🟢 在手机 App 接口的设备列表中，新增设备所属节点服务器信息，包括对应域名与 IP 地址。
    • 🟢 设备所属服务器信息接口：获取设备关联的节点服务器详情，包含对应域名及 IP 地址
    • 🟢 手机 App 设备绑定接口安全加固：
      • 引入设备生成的授权码机制，用户需通过手机 App 采集设备上的授权码并提交至服务端进行验证。
      • 服务端基于内部加密逻辑校验授权码的有效性。若验证失败，返回相应错误信息；验证成功后，执行以下绑定逻辑：
        • 无历史绑定记录 服务器未查询到该设备的已有授权码，直接完成绑定，并返回绑定成功响应。
        • 存在相同授权码 服务器查到该设备已有相同授权码，表明已绑定：
          • 若用户名一致，返回“重复绑定”提示；
          • 若用户名不一致，返回“设备已绑定至用户：xxx”提示。
        • 存在不同授权码 服务器查到的历史授权码与当前提交的不同：
          • 若用户名一致，更新授权码并返回成功；
          • 若用户名不一致，执行授权切换：更新授权码，解绑原用户，绑定新用户，并返回成功响应。

其它

  • 目标: 记录日常耗时的杂项工作、协作事项，以及必要的沟通、讨论等隐性事务。
  • 进度: 属非计划内事务（🟢 未开始 | 🟡 进行中 | ⚠️ 部分完成 | ✅ 已完成 | 📌 已验证）
    • 01 日
      • ✅ 完成办公环境整理，保持桌面整洁有序，包括个人工作区域及新员工预备工位。
      • ✅ 优化长沙办公室设备布局，将两台服务器迁移至打印机区域集中放置，释放出一个可用工作台面，提升空间利用率。
      • ✅ 将登录验证码由6位调整为4位，优化用户输入体验，提升登录便捷性。
      • ✅ 在 WebRTC 播放器左下角新增状态图标，根据当前网络连接类型动态显示：P2P 或 转发，便于用户直观识别连接模式。
    • 02 日
      • ✅ 线下面试 dms 岗应聘者
      • ✅ es-center-server-device-service 及 es-center-server-main-service 所依赖的第三方库小版本升级：
      • ✅ es-center-server-install-app 需部署的第三方中间件 docker 映像小版本升级：
        • coturn [4.6.3-alpine -> 4.7.0-alpine]
        • ActiveMQ Artemis [2.41.0-alpine -> 2.44.0-alpine]
        • emqx [5.8.6-alpine -> 5.8.8-alpine]
        • nginx [1.28.0-alpine -> 1.29.3-alpine]
        • meilisearch [v1.18.0 -> v1.28.1-alpine]
      • ✅ es-center-server-web-app 所依赖的第三方库小版本升级：
        • @react-three/drei [^10.7.6 → ^10.7.7]
        • @react-three/fiber [^9.4.0 → ^9.4.2]
        • @turf/turf [^7.2.0 → ^7.3.1]
        • gojs [^3.1.0 → ^3.1.2]
        • react-day-picker [9.11.1 → 9.11.3]
        • recharts [2.15.4 → 3.5.1]
        • three [^0.181.0 → ^0.181.2]
        • three-stdlib [^2.36.0 → ^2.36.1]
      • ✅ 完成国内版最新版本的安装包构建及升级部署，按流程先行发布至 zxs-cs 自测环境并完成验证，随后部署至 zxs 正式环境
    • 03 日
      • ✅ 新员工入职培训：提供技术资料及介绍大概情况
      • ✅ 完成国际版最新版本的安装包构建及升级部署，按流程先行发布至 zxs-ca 自测环境并完成验证，随后部署至 zxs-hs 正式环境
      • ✅ 轻量化分布式部署讨论：讨论了轻量化分布式部署的架构设计及实现细节
      • ✅ 轻量化分布式部署过渡阶段 — 服务端任务分解与梳理: 持续推进服务端向轻量化分布式架构演进，聚焦模块拆分、配置管理、通信优化与容器化部署，保障系统平稳过渡与可维护性提升。
      • ✅ 指导新员工熟悉现有前端项目结构，为后续的开发工作打下基础。
    • 04 日
      • Nacos 集成落地方案细节讨论：围绕跨境服务的稳定性保障与配置治理，明确共用配置与专属配置的分层管理策略，确立境内主控、境外只读、增量同步的技术路径，确保配置一致性与系统高可用。
      • ✅ 新员工开发任务安排与需求说明
    • 04 日
      • ✅ 新员工开发任务评审：从代码质量、业务逻辑清晰性、需求与实现的一致性等方面进行全面评估

总结

  • coturn 因网络限制无法拉取 Docker 镜像，导致离线包导出为空（0 KB），进而造成升级过程中镜像导入失败
  • 第三方依赖库 springdoc-openapi-starter-webmvc-ui 从 2.8.9 升级至 3.0.0 后回退，原因为 3.0.0 版本依赖 Spring Boot 4.0.0，与当前项目使用的 3.5.8 版本不兼容
  • Meilisearch 升级失败的根本原因在于版本跨度较大（1.18.0 → 1.28.1），其间数据库存储格式发生不兼容变更，无法直接读取旧版数据。Meilisearch 要求遵循“渐进式升级”原则，即通过连续的小版本逐步迁移，或采用“数据导出 + 重新导入”方式进行跨版本升级。为此，调整升级策略为分阶段递进升级（1.18 → 1.20 → 1.25 → 1.28），利用 Meilisearch 对前 1–2 个旧版本的兼容性，由各中间版本自动完成数据库结构迁移

Nacos 集成方案

方案2（境外部署本地Nacos+同步境内配置）分步实施指南

整体架构回顾

  • 境内：1台固定主节点Nacos（禁用自动选主），存储「共有配置+境内专属配置+境外专属配置」（按Namespace=类别、Group=域名划分）；
  • 境外：部署1~3台Nacos（建议至少2节点做本地高可用，禁用自动选主），仅作为「配置同步从节点+境外程序的本地配置服务端」，禁止境外直接修改配置（所有配置变更仅在境内主节点操作）；
  • 数据流向：境内主节点配置变更 → 境外Nacos定时/增量同步境内配置 → 境外Spring Boot程序读取本地Nacos配置；
  • 核心原则：境外Nacos仅“读+同步”，境内Nacos仅“写+主数据存储”，保证配置唯一数据源。

分步实施（共7阶段，从基础到落地全覆盖）

阶段1：前期准备（1~2天）

目标

完成环境、配置规划、权限梳理，避免后续返工。

核心操作

  1. 环境适配检查
    • 境内/境外服务器环境统一：JDK8+/11（Nacos 2.x推荐JDK11）、内存（境内主节点≥1G，境外节点≥512M）、网络（境内主节点开放8848端口给境外Nacos IP白名单，境外内网互通）；
    • 域名规划落地：按「Namespace=类别、Group=域名」梳理配置清单（示例如下），并在境内DNS配置好域名解析（仅境内主节点IP）：
境内Namespace（类别）境内Group（域名）配置类型同步范围
publiccommon.xxx.com共有配置境内+所有境外
cncn-east.xxx.com华东境内专属仅境内
globalus-north.xxx.com北美境外专属仅北美境外
globaleu-west.xxx.com欧洲境外专属仅欧洲境外

  1. 权限梳理

    • 境内Nacos：创建2类账号——「配置管理员」（可修改所有配置）、「境外同步账号」（仅只读权限，用于境外Nacos同步）；
    • 境外Nacos：仅创建「境外程序只读账号」（禁止任何写操作），配置修改仅能在境内主节点完成。

  2. 工具准备

    • 境内/境外Nacos版本统一：建议用Nacos 2.3.2（稳定版），下载地址：https://github.com/alibaba/nacos/releases/tag/2.3.2； 
    • 同步工具：优先用Nacos Open API（原生无依赖），或封装Python/Java脚本（实现增量同步+重试）；
    • 监控工具：Prometheus+Grafana（监控境内/境外Nacos健康状态、同步成功率）。

阶段2：境内Nacos主节点配置优化（0.5天）

目标

让境内Nacos适配“跨境同步”，并固化主节点（禁用自动选主）。

核心操作

  1. 固化境内主节点（关键） 修改境内Nacos安装目录下conf/application.properties：

    # 禁用Raft自动选主，固定单主节点
nacos.core.protocol.raft.enable=false
nacos.core.protocol.raft.auto-failover=false
# 仅保留自身IP，禁止集群选主
cluster.conf=境内主节点内网IP:8848
# 开启配置历史版本（便于同步异常时回滚）
nacos.config.history.enable=true
nacos.config.history.retention-days=7
# 开放API权限（给境外同步账号）
nacos.plugin.auth.enabled=true
nacos.plugin.auth.token.secret.key=自定义密钥（32位以上）
nacos.plugin.auth.server.identity.key=serverIdentity
nacos.plugin.auth.server.identity.value=custom

    重启境内Nacos，验证：访问http://境内主节点IP:8848/nacos，确认无“集群节点”提示，仅显示自身节点。

  2. 配置结构落地 在境内Nacos控制台按阶段1的清单创建Namespace（public/cn/global），并在对应Namespace下创建Group（域名），导入已有配置（共有/境内专属/境外专属）。

  3. 同步账号授权 在境内Nacos控制台→权限管理→用户管理，创建「境外同步账号」（如sync_foreign），仅授予「只读权限」，并绑定到所有需要同步的Namespace。

阶段3：境外Nacos集群部署（1天）

目标

部署境外本地Nacos，仅作为“同步从节点+本地服务端”，禁用写能力。

核心操作

  1. 境外Nacos部署（以2节点为例）

    • 节点1/2均执行：解压Nacos安装包，修改conf/application.properties： 
      # 禁用自动选主（境外仅作为本地服务端，无需选主）
nacos.core.protocol.raft.enable=false
# 境外Nacos仅提供本地服务，不参与集群选主
cluster.conf=境外节点1IP:8848,境外节点2IP:8848
# 禁用配置写入（核心：仅允许同步，禁止境外修改）
nacos.config.writable=false
# 开启本地缓存（降低同步压力）
nacos.config.local-cache.enable=true
nacos.config.local-cache.expire=3600
# 监控配置（便于后续接入Prometheus）
management.endpoints.web.exposure.include=*
    • 启动境外Nacos：sh bin/startup.sh -m standalone（单节点模式，多节点仅需分别启动，无需集群配置）；
    • 验证：访问http://境外节点1IP:8848/nacos，确认“配置管理”模块仅显示“只读”，无新增/修改按钮。

  2. 境外Nacos内网互通验证 境外节点1/2互相访问http://对方IP:8848/nacos，确保内网连通；境外Spring Boot程序服务器能ping通境外Nacos节点IP。

阶段4：境内→境外Nacos配置同步方案落地（核心，1~2天）

目标

实现境内配置变更后，境外Nacos自动同步，优先“增量同步”（降低跨境带宽）。

核心方案：基于Nacos Open API的增量同步（推荐）

Nacos原生Open API支持“按配置MD5/修改时间查询变更配置”，适合跨境同步（仅同步变更，减少网络消耗）。

  1. 同步逻辑设计

    • 触发方式：定时触发（推荐5分钟/次，可按配置变更频率调整）；
    • 同步范围：按Namespace+Group过滤（如北美境外仅同步public+global/us-north.xxx.com）；
    • 容错机制：失败重试（3次）、断点续传（记录最后同步时间戳）、同步日志留存（便于排查）。

  2. 同步脚本开发（Python示例，可改用Java） 脚本部署在境外Nacos节点（或境外专用同步服务器），核心逻辑：

    import requests
import time
import hashlib
 
# 配置项
# 境内主节点信息
INNER_NACOS_URL = "http://境内主节点公网IP:8848/nacos"
# 境外Nacos信息（多节点可轮询）
OUTER_NACOS_URL = "http://境外节点1IP:8848/nacos"
# 境内同步账号
SYNC_USER = "sync_foreign"
SYNC_PWD = "同步账号密码"
# 同步范围：北美境外仅同步public+global/us-north.xxx.com
SYNC_CONFIG = [
    {"namespace": "public", "group": "common.xxx.com"},
    {"namespace": "global", "group": "us-north.xxx.com"}
]
# 最后同步时间戳（首次为0）
LAST_SYNC_TIME = 0
 
# 1. 境内Nacos登录获取token
def get_inner_token():
    login_url = f"{INNER_NACOS_URL}/nacos/v1/auth/users/login"
    resp = requests.post(login_url, data={"username": SYNC_USER, "password": SYNC_PWD})
    return resp.json()["accessToken"]
 
# 2. 查询境内变更配置（按修改时间）
def get_changed_configs(token):
    changed_configs = []
    for item in SYNC_CONFIG:
        namespace = item["namespace"]
        group = item["group"]
        # 查询境内该Namespace+Group下所有配置
        list_url = f"{INNER_NACOS_URL}/nacos/v1/cs/configs?accessToken={token}&namespaceId={namespace}&group={group}&pageNo=1&pageSize=1000"
        resp = requests.get(list_url).json()
        # 筛选出最后同步时间后修改的配置
        for config in resp["pageItems"]:
            if int(config["modifyTime"]) > LAST_SYNC_TIME:
                changed_configs.append({
                    "dataId": config["dataId"],
                    "group": group,
                    "namespace": namespace,
                    "content": config["content"],
                    "md5": config["md5"]
                })
    return changed_configs
 
# 3. 同步变更配置到境外Nacos
def sync_to_outer(configs):
    # 境外Nacos无需登录（仅读，同步时用管理员账号）
    outer_token = "境外Nacos管理员token"
    success_count = 0
    fail_count = 0
    for config in configs:
        sync_url = f"{OUTER_NACOS_URL}/nacos/v1/cs/configs?accessToken={outer_token}"
        data = {
            "dataId": config["dataId"],
            "group": config["group"],
            "namespaceId": config["namespace"],
            "content": config["content"],
            "type": "yaml"
        }
        try:
            resp = requests.post(sync_url, data=data, timeout=10)
            if resp.text == "success":
                success_count += 1
            else:
                fail_count += 1
                print(f"同步失败：{config['dataId']}，原因：{resp.text}")
        except Exception as e:
            fail_count += 1
            print(f"同步异常：{config['dataId']}，原因：{str(e)}")
    return success_count, fail_count
 
# 主逻辑
if __name__ == "__main__":
    try:
        token = get_inner_token()
        changed_configs = get_changed_configs(token)
        if not changed_configs:
            print("无变更配置，无需同步")
            exit(0)
        success, fail = sync_to_outer(changed_configs)
        # 更新最后同步时间戳
        LAST_SYNC_TIME = int(time.time() * 1000)
        print(f"同步完成：成功{success}个，失败{fail}个")
    except Exception as e:
        print(f"同步脚本异常：{str(e)}")

  3. 脚本部署与定时执行

    • 将脚本部署在境外Nacos节点，命名为nacos_sync.py；
    • 配置crontab定时执行（5分钟/次）：*/5 * * * * /usr/bin/python3 /opt/nacos_sync.py >> /opt/nacos_sync.log 2>&1；
    • 验证：在境内Nacos修改global/us-north.xxx.com下的配置，等待5分钟后，查看境外Nacos控制台，确认配置已同步。

  4. 同步容错优化

    • 脚本中增加“MD5校验”：同步后对比境内外配置MD5，不一致则重新同步；
    • 失败重试：单次同步失败后，间隔1分钟重试，最多3次；
    • 日志留存：同步日志保留7天，便于排查跨境同步失败原因（如网络超时、权限不足）。

阶段5：境外Spring Boot程序适配（0.5~1天）

目标

境外程序从“直连境内Nacos”改为“连本地Nacos”，配置逻辑不变（Namespace+Group仍对齐境内）。

核心操作

  1. 修改程序配置文件（application.yml） 仅需修改server-addr为境外Nacos节点地址，其余配置（Namespace、Group、shared-configs）完全复用境内逻辑：

    spring:
  cloud:
    nacos:
      config:
        # 改为境外本地Nacos地址（多节点用逗号分隔）
        server-addr: 境外节点1IP:8848,境外节点2IP:8848
        # 仍对齐境内的Namespace+Group（无需修改）
        namespace: global
        group: us-north.xxx.com
        # 叠加共有配置（同步自境内public/common.xxx.com）
        shared-configs:
          - data-id: common-config.yaml
            namespace: public
            group: common.xxx.com
            refresh: true
        # 境外本地访问优化（无需跨境，超时可降低）
        timeout: 3000ms
        retry:
          max-attempts: 2
        # 保留本地缓存（双重兜底）
        cache-enabled: true
      discovery:
        # 服务发现也连境外本地Nacos
        server-addr: 境外节点1IP:8848,境外节点2IP:8848
        namespace: global
        group: us-north.xxx.com

  2. 程序验证

    • 启动境外Spring Boot程序，查看日志：确认“Loaded nacos config”来自境外Nacos；
    • 修改境内Nacos的us-north.xxx.com下的配置，等待同步脚本执行后，触发程序配置刷新（如调用/actuator/refresh），验证配置是否更新。

阶段6：监控&容灾&全量验证（1天）

目标

建立全链路监控，确保跨境同步/境外服务稳定。

  1. 监控指标接入（Prometheus+Grafana）

    • 境内/境外Nacos均开启监控：修改conf/application.properties，增加management.endpoints.web.exposure.include=*；
    • 监控核心指标：
      • 同步层：同步成功率（≥99.9%）、同步延迟（≤5分钟）、跨境网络连通性；
      • Nacos层：境内/境外Nacos节点存活状态、配置查询QPS、本地缓存命中率；
      • 程序层：境外程序配置加载成功率（100%）、配置刷新耗时（≤100ms）。

  2. 容灾场景验证

    测试场景预期结果
    跨境网络中断（断网30分钟）境外程序仍能从本地Nacos读取配置，核心业务无影响；跨境恢复后，同步脚本自动补全配置
    境内主节点故障（停机1小时）境外Nacos仍提供本地配置服务，程序无感知；境内恢复后，同步脚本补全最新配置
    境外单个Nacos节点故障境外程序自动切换到另一节点，配置读取无中断

  3. 配置一致性验证 随机抽取10个配置项，对比境内Nacos、境外Nacos、境外程序加载的配置值，确保完全一致（同步延迟内）。

阶段7：灰度上线&全量切换（1~2天）

目标

平稳切换所有境外程序到本地Nacos，避免批量故障。

  1. 灰度策略

    • 第一步：选择1~2台非核心境外程序，切换到本地Nacos，观察24小时；
    • 第二步：切换核心程序（分批次，每批次观察1小时）；
    • 第三步：全量切换完成后，保留1台程序直连境内Nacos作为“备用验证节点”，运行7天后下线。

  2. 回滚预案 若境外本地Nacos出现异常，可快速将境外程序的server-addr改回境内主节点IP，恢复直连模式（配置无需其他修改）。

关键注意事项（稳定性保障）

  1. 境外Nacos仅读：严格禁止在境外Nacos控制台修改配置，所有变更必须在境内主节点操作，避免配置孤岛；
  2. 同步频率平衡：同步频率过高（如1分钟/次）会增加跨境带宽，过低（如1小时/次）会导致配置更新延迟，建议5~15分钟/次；
  3. 跨境网络优化：境内主节点仅开放8848端口给境外Nacos IP白名单，禁止公网裸连；优先用CN2 GIA/MPLS专线承载同步流量；
  4. 配置加密：若配置含敏感信息（如数据库密码），境内/境外Nacos均开启配置加密（Nacos 2.x原生支持），避免跨境传输泄露。

实施周期&人力评估

阶段耗时核心人力
前期准备1~2天架构师+运维
境内Nacos优化0.5天运维
境外Nacos部署1天运维
同步脚本开发1~2天开发
程序适配0.5~1天开发+测试
监控&容灾1天运维+监控工程师
灰度&全量切换1~2天运维+开发+测试
总计6~9天2~3人

最终效果

  • 稳定性：境外程序完全摆脱跨境网络依赖，配置加载/刷新延迟≤50ms，跨境断网时核心业务无影响；
  • 一致性：境内是唯一配置数据源，境外同步延迟可控（5~15分钟），满足绝大多数跨境业务需求；
  • 可维护性：配置修改仅在境内操作，境外无需介入，降低多地域运维成本。
Last updated on
2025年11月24日2025年12月08日