NodeXA 是运行在 Linux 主机上的现代化运维与应用管理平台。它把资源、应用、运维、安全和自动化能力放进一个多页面工作区，让一次排查或发布可以保留完整上下文。

NodeXA 适合做什么

• 查看 CPU、内存、磁盘、网络、进程、端口和服务。
• 在受控文件工作区和 Web 终端中处理主机问题。
• 管理 Docker、常用软件、数据库和中间件。
• 创建静态网站、反向代理和应用运行环境。
• 申请、使用、续期、解绑、删除或吊销 TLS 证书。
• 查询日志与监控趋势，运行任务，创建和恢复备份。
• 管理防火墙、SSH、安全评分、会话和审计记录。

NodeXA 的边界

NodeXA 当前聚焦单台主机。它不是 Kubernetes 替代品，也不是多租户云控制平台。核心数据保存在你的主机上，公网暴露方式、操作系统更新、主密钥保护和离线备份仍由你负责。

接下来

先检查系统要求，然后按照安装指南部署第一台 NodeXA 主机。

必要条件

NodeXA 的基础功能不要求 Docker。网站运行时、容器应用以及部分软件实例需要 Docker Engine 与 Compose v2；Docker 页面可以对受支持发行版提供安装协助。

推荐资源

具体资源取决于容器、日志和指标保留量。仅运行 NodeXA 时建议至少预留：

• 1 个 CPU 核心。
• 1 GB 可用内存。
• 2 GB 可用磁盘空间，并为日志、备份和应用数据另行规划容量。

网络要求

默认情况下，浏览器只能从主机本地访问 http://127.0.0.1:8080。远程使用推荐：

1. 在 NodeXA 前配置 HTTPS 反向代理。
2. 仅开放实际需要的端口。
3. 正确配置可信代理。
4. 在可信网络完成首次初始化。

安装前检查

uname -a
id
command -v systemctl || command -v service
ss -lnt | grep ':8080'

确认端口未被占用后继续阅读安装。

前置条件

• 已满足系统要求。
• 已从可信发布渠道取得与系统架构匹配的 NodeXA 二进制。
• 已核对发布清单、SHA-256 和签名。
• 当前账号可以使用 sudo。

安装为系统服务

在下载目录执行：

chmod +x rovia
sudo ./rovia install
sudo ./rovia status

install 会探测 systemd 或 SysV，写入服务定义并默认启用开机自启。需要覆盖默认路径时先查看帮助：

./rovia help

可选参数包括二进制路径、配置路径、工作目录、运行用户及 --no-enable。

验证

状态输出应表明服务已经安装、正在运行并按预期启用。然后在主机本地执行：

curl -I http://127.0.0.1:8080

收到 HTTP 响应后，进入首次初始化。

失败处理

1. 使用 sudo ./rovia status 查看服务状态。
2. systemd 主机使用 journalctl -u rovia --no-pager -n 100 查看启动日志。
3. 检查工作目录、配置文件权限和 8080 端口占用。
4. 修复问题后执行 sudo ./rovia restart。

回退

尚未写入业务数据时可执行：

sudo ./rovia uninstall

卸载服务不会自动代表业务数据已经安全删除。处理工作目录前先确认是否需要保留配置、数据库和备份。

访问初始化页

NodeXA 默认监听 127.0.0.1:8080。在主机本地打开：

http://127.0.0.1:8080

远程主机可先建立 SSH 端口转发：

ssh -L 8080:127.0.0.1:8080 user@host

然后在本机浏览器打开同一地址。

创建管理员

首次启动进入初始化页，而不是普通登录页。按照页面要求：

1. 设置管理员账号。
2. 使用唯一且足够长的密码。
3. 保存恢复所需信息。
4. 完成初始化并重新登录。

首次登录后的建议

• 在设置中核对监听、代理和平台参数。
• 绑定 TOTP MFA 并安全保存恢复码。
• 检查会话列表，确认只有当前设备。
• 配置并备份 Secret 主密钥。
• 创建第一份 NodeXA 备份。
• 运行安全扫描，逐项确认风险。

验证

退出并重新登录一次，确认账号和密码正常；随后打开工作台、主机、服务和日志页面，确保基础采集没有错误。

无法进入初始化页时，参考故障排查。

常用命令

sudo rovia start
sudo rovia stop
sudo rovia restart
sudo rovia status

如果二进制不在 PATH，使用安装时的绝对路径。

前台运行

排查启动问题时可暂时停止系统服务，并在工作目录前台运行：

rovia run

前台运行会占用当前终端。验证完成后使用 Ctrl+C 停止，再恢复系统服务。

卸载服务

sudo rovia uninstall

卸载会停止、禁用并删除服务定义。它不会替你判断哪些数据库、配置、备份和应用数据可以删除。

验证

执行 status 并结合系统服务工具检查状态：

systemctl status rovia --no-pager

SysV 主机使用对应的 service 命令。

NodeXA 使用 YAML 配置。安装为系统服务后，配置文件路径由服务定义和安装参数决定，不应只根据当前 Shell 目录猜测。

修改前

1. 使用 rovia status 确认服务与工作目录。
2. 创建 NodeXA 备份。
3. 复制当前配置文件。
4. 记录修改原因和预期验证方式。

关键配置领域

• HTTP 监听地址和可信代理。
• SQLite 与运行数据目录。
• 日志级别、日志文件和轮转。
• 软件、备份、终端和文件工作区目录。
• 安全扫描、Session TTL 与主密钥来源。
• 更新源和可信签名公钥。

应用配置

修改配置后重启：

sudo rovia restart
sudo rovia status

再检查日志和健康接口。若启动失败，立即恢复备份配置并再次重启。

网络提示

默认 127.0.0.1:8080 是安全基线。修改为全网卡监听会扩大攻击面；在公网场景优先保留回环监听，并通过受控反向代理提供 HTTPS。

密码与用户

在设置中管理当前管理员凭据。修改密码后，使用新的独立浏览器会话验证登录，再退出旧会话。

会话管理

会话页展示当前和其他登录设备。发现不认识的会话时：

1. 先吊销异常会话。
2. 修改管理员密码。
3. 检查审计和登录事件。
4. 确认主机和反向代理日志没有异常来源。

TOTP MFA

绑定流程会显示二维码和恢复码：

1. 使用可信认证器扫描二维码。
2. 输入一次动态验证码确认绑定。
3. 将恢复码保存在独立、安全的位置。
4. 退出并测试 MFA 登录。

Step-up 二次认证

高风险操作会要求重新验证身份。Step-up 是短时授权，不代表后续所有操作永久放行。常见触发点包括：

• 修改关键设置。
• 恢复备份。
• 管理软件密钥与 Secret。
• 创建或运行高权限 Shell 任务。
• 防火墙、SSH 和部分容器变更。

若频繁验证失败，检查主机时间、认证器时间和会话是否已经过期。

NodeXA 使用 Secret Store 保存数据库密码、DNS 提供商 Token 等敏感值。Secret 使用 AES-GCM 加密，主密钥不应存入同一业务数据库。

主密钥原则

• 使用高熵随机值。
• 只授予 NodeXA 服务账号读取权限。
• 不写入版本库、普通日志或截图。
• 保存一份受保护的离线副本。
• 备份恢复时同时确认主密钥可用。

轮换

轮换前：

1. 创建并验证 NodeXA 备份。
2. 确认当前主密钥可读。
3. 准备新密钥的安全存放位置。
4. 选择维护窗口。

轮换后验证网站证书提供商、数据库实例和所有使用 Secret 的任务。发生错误时不要删除旧密钥，先停止写入并按恢复文档回退。

审计

Secret 页面不应回显完整明文。创建、更新和删除动作应进入审计记录，但审计字段同样不能包含 Secret 内容。

主机页面聚合操作系统、CPU、内存、磁盘和网络信息。工作台摘要和趋势图来自本机采集，不代表公网可用性。

查看资源状态

• CPU 使用率和负载用于发现持续繁忙或突发任务。
• 内存同时关注已用量、缓存和 Swap。
• 磁盘重点关注容量、挂载点和增长趋势。
• 网络趋势用于发现流量变化，不能替代链路质量监控。

排查路径

发现异常时建议按上下文继续：

1. 打开进程页面定位资源使用者。
2. 查看对应 systemd 服务或容器。
3. 查询 journald、应用或网站日志。
4. 必要时打开 Web 终端执行只读检查。
5. 变更后返回趋势页验证效果。

磁盘告警处理

不要直接删除不认识的目录。先确认增长来源，检查日志轮转、备份保留和容器数据，再在维护窗口清理。

文件页面是本机文件系统管理器：打开后直接从系统根目录 / 浏览，登录后即可读写（上传、新建、编辑、移动、删除），无需再手动添加工作区根目录，也不再要求 Step-up 二次认证。

文本编辑器支持：

• CodeMirror：行号、语法高亮（按扩展名）、查找替换（Ctrl/⌘+F）、软换行、Ctrl/⌘+S 保存
• 未保存关闭确认、etag 冲突提示（重新加载 / 强制覆盖）
• 保存前可选备份为同目录 .bak
• 超限大文件只读预览；绝对路径、权限与属主展示
• 左侧目录 + 右侧编辑分屏

支持的操作

• 浏览目录与查看基础属性。
• 上传和下载文件。
• 创建目录。
• 重命名和移动。
• 编辑文本文件。
• 删除到回收站。
• 从回收站恢复或永久清理。

路径安全

符号链接在目标仍位于系统根下时可以进入；设备文件、FIFO、套接字等非常规入口会被跳过或拒绝。路径会经过规范化以阻止 .. 逃逸。实际能否读写仍受 NodeXA 进程操作系统权限限制。

删除与恢复

普通删除优先进入回收站。永久清理前确认：

• 回收站条目有保留期，过期由后台清理。
• 恢复时目标路径若已存在新文件，可能冲突失败。

权限说明

NodeXA 服务以何种用户运行，就对应何种文件系统权限。若某目录列出为空或写入失败，优先检查进程用户对该路径的读写权限，而不是放宽整盘权限。

Web 终端通过 WebSocket 提供交互式 Shell。安装流程会准备专用的 rovia-terminal 用户，避免默认以 root 打开浏览器终端。

建立连接

1. 打开“资源 / 终端”。
2. 等待票据创建和 WebSocket 连接完成。
3. 检查页面显示的运行用户、Shell 和连接状态。
4. 输入只读命令验证当前目录与身份。

whoami
pwd
id

安全机制

• 短时终端票据。
• WebSocket 首帧认证。
• Origin 校验。
• 会话数量与空闲限制。
• 专用低权限用户。
• 连接和结束事件审计。

断线

网络切换、反向代理超时或 Session 失效可能导致断线。先确认页面状态，不要在不确定上一条命令是否完成时立即重复执行变更命令。

结束会话

完成工作后退出 Shell 并关闭终端页签。不要只关闭浏览器窗口而长期保留高权限子进程。

进程页面用于观察运行状态，服务页面用于管理 systemd 单元和由软件模块托管的应用服务。

进程与端口

可按名称、PID、用户或资源占用查找进程，并结合监听端口判断服务入口。终止进程前先确认它是否由 systemd、Docker 或其他监督器管理，否则进程可能立即被重新拉起。

systemd 服务

支持的生命周期操作包括：

• 启动。
• 停止。
• 重启。
• 启用或禁用开机启动。

推荐排查顺序

1. 查看服务当前状态和最近错误。
2. 打开对应 journald 日志。
3. 检查端口冲突、权限和配置。
4. 修复后重启服务。
5. 返回日志和健康页面验证。

回退

启用状态变更可恢复原状态；配置导致服务失败时，应恢复配置备份后再重启，而不是连续点击重启。

Docker 页面展示本机安装状态、版本、容器和镜像。NodeXA 也可根据操作系统发行版与版本提供 Docker 安装协助。

安装前检查

• 确认操作系统与软件源受支持。
• 检查已有 Docker、Podman 或发行版包是否冲突。
• 确认磁盘和网络空间。
• 了解安装会修改软件源、软件包和服务状态。
• 完成 Step-up 验证。

容器操作

NodeXA 提供容器启动、停止和重启入口。删除容器、镜像或卷前检查：

• 容器是否由 Compose 或 NodeXA 应用运行环境管理。
• 数据是否位于具名卷或绑定目录。
• 是否有可恢复备份。
• 删除后是否能从声明式配置重建。

验证

docker version
docker compose version
docker info

在页面中确认版本、守护进程状态和容器列表与 CLI 一致。

故障处理

安装失败时保留安装日志，检查发行版代号、软件源、代理、DNS 和包管理锁。不要在失败后混用多个来源重复安装。

网站模块把站点、Caddy 运行时、证书、日志、健康和备份统一归口。NodeXA 管理结构化配置并生成 Caddy 配置，而不是鼓励直接编辑 Caddyfile。

统一根目录

网站相关文件统一位于 NodeXA 工作目录下的 website 根目录：

• 站点配置与生成的 Caddyfile。
• 静态文件与站点目录。
• 手动证书。
• Caddy 数据（自动证书、TLS 私钥）。
• 访问日志与运行日志。
• 备份与临时文件。

运行时

v0.2.4 起网站由 Caddy 承载：

• 缺少 Caddy 时，网站工作台会检测并提供「下载并安装官方标准版 Caddy」（Linux amd64 / arm64，含 SHA-256 与版本校验）。
• 安装后可启动、停止、重启并查看 Caddy 运行日志。
• Caddy 以非 root 身份运行；管理 Socket 不对外监听。
• 新站点默认使用 Caddy 自动 HTTPS；已有 NodeXA 证书仍可手动绑定。

创建网站

创建向导包含：

1. 选择静态目录、反向代理或 HTTP 重定向类型。
2. 设置名称、域名和监听方式。
3. 配置站点目录或上游。
4. 选择 TLS 模式与证书。
5. 预览并提交草稿。

TLS 模式

发布流程

提交后配置先处于草稿或待应用状态。应用时 NodeXA：

1. 渲染受管配置并组装完整候选配置树。
2. 使用 caddy validate 验证完整配置（能发现跨站点域名冲突等错误）。
3. 原子替换活动配置并 reload。
4. 探测站点可达性。

任一步失败时恢复最后一个确认可用的配置，不把无效配置标记为生效。两个站点并发发布会被串行化，不会互相覆盖。

应用后 NodeXA 会从本机探测站点；若域名解析指向其他主机，本机探测失败不代表站点未发布，可先用客户端 Hosts / DNS 验证。

配置漂移

若在 NodeXA 外部修改受管文件，页面可能提示配置漂移。先比较当前配置和最后成功发布版本，再选择重新应用或接受外部变更，不要盲目覆盖。

日常维护

• 查看 Caddy JSON Lines 访问日志与 Caddy 运行日志。
• 检查站点健康和延迟。
• 管理 TLS 证书（自动 HTTPS、手动证书、仅 HTTP）。
• 创建站点备份（包含 Caddy 数据时备份会标注敏感警告）。
• 查看发布历史并恢复为草稿。

站点恢复默认只生成草稿，需人工检查后重新应用。

应用运行环境使用受控容器部署应用，并可作为网站反向代理上游。

支持的引擎

• Node.js。
• Bun。
• Python。
• PHP-FPM。

实际镜像、版本和命令以创建向导支持矩阵为准。

创建应用

1. 选择引擎与环境。
2. 提供受控源码目录。
3. 配置安装、构建和启动命令。
4. 设置监听端口、CPU、内存和 PID 限额。
5. 添加普通环境变量和 Secret 引用。
6. 提交应用草稿。
7. 部署并等待健康检查。

强制安全约束

• 非 root 用户。
• 只读根文件系统。
• 仅回环地址或内部网络发布。
• CPU、内存和 PID 限制。
• 构建容器不挂载 Docker Socket。
• Secret 通过受控方式注入。

连接网站

应用健康后可由网站模块选择为反向代理上游。健康失败时应先修复应用，不要通过绕过健康检查把错误实例直接发布。

备份与回滚

备份范围需区分源码、声明式配置、环境变量引用和持久化数据。容器本身不是备份。恢复后先验证草稿和数据路径，再发布网站。

NodeXA 提供多种证书方案协助。选择方案前先判断域名解析位置、是否经过 Cloudflare 代理、是否需要通配符和浏览器直接信任。

方案比较

HTTP-01

• 域名 A/AAAA 记录指向当前主机。
• 公网可访问 80 端口。
• 反向代理不能阻断 ACME challenge。
• 签发前先运行预检。

DNS-01 与 Cloudflare

创建最小权限 API Token，只授权目标 Zone 的 DNS 编辑。Token 存入 Secret Store，不在日志和页面中完整回显。

DNS 传播存在延迟。签发失败时先检查权威 DNS 记录，不要短时间高频重试触发 CA 限流。

使用与替换

一个网站同一时间只有一个活动证书。替换前检查域名覆盖和有效期，应用后使用浏览器或 TLS 工具验证证书链。

解绑、删除和吊销

• 解绑：网站不再引用证书，证书记录仍保留。
• 删除：移除 NodeXA 中的证书记录和受管文件，不能代替 CA 吊销。
• 吊销：通知 CA 证书不再可信，通常不可逆。

吊销前确认证书确实泄露、域名不再使用或 CA 要求吊销。一般替换或停用不需要立即吊销。

自动续期

自动 HTTPS 模式下，证书由 Caddy 自动申请和续期，无需人工干预。手动证书路径下，续期任务应在到期前运行，成功后原子替换并重新加载，让 Caddy 加载新证书。连续失败需要产生告警；到期前不要删除仍在使用的旧证书。

软件模块提供目录、环境预检、安装和实例生命周期。数据库、中间件和应用页面是按用途聚合的视图，底层实例仍由软件模块统一管理。

安装来源

• systemd 本地服务。
• Docker Compose 托管实例。

安装前预检会根据来源检查可执行文件、端口、目录、Docker 和 Compose。

安装流程

1. 从目录选择软件。
2. 查看来源、依赖、端口和数据目录。
3. 完成环境预检。
4. 配置实例名和 Secret。
5. 提交安装并查看日志。
6. 验证服务状态和访问方式。

生命周期

支持启动、停止、重启和卸载。卸载前需要确认：

• 是否同时删除数据。
• 是否有其他应用依赖。
• 是否已经完成逻辑备份。
• Secret 和端口是否仍被其他实例引用。

审计

安装、启停、重启和卸载均属于关键操作，应记录实例、来源、结果和操作者。

任务模块用于管理本机定时或手动任务，并保存运行状态与历史。

创建任务

1. 设置名称和说明。
2. 选择调度表达式。
3. 配置任务类型和参数。
4. 对 Shell 任务明确运行用户与 Shell。
5. 预览下一次运行时间。
6. 保存后手动运行一次验证。

Shell 安全

Shell 任务必须明确 run_as 和 Shell 策略。旧任务若缺少这些字段会被标记为待确认，不应在未检查内容的情况下直接恢复调度。

运行历史

查看：

• 计划与实际开始时间。
• 结束时间和持续时长。
• 成功、失败或取消状态。
• 安全截断后的输出。

任务失败时先修复原因，再手动运行验证，不要通过缩短间隔反复重试。

回退

对有副作用的任务准备反向操作或备份。禁用任务不会撤销已经完成的变更。

日志用于解释事件，监控用于发现趋势。两者需要结合服务、进程、容器和网站健康状态使用。

journald

选择允许的 systemd 单元，按时间、级别和关键词查询。查询范围过大时先缩短时间窗口，再定位错误上下文。

文件日志

NodeXA 只允许读取配置白名单中的文件路径，并进行真实路径检查。新增来源前确认：

• 文件不包含长期 Secret。
• NodeXA 服务用户具有只读权限。
• 路径不会通过符号链接逃逸。
• 已配置日志轮转。

指标

主机指标包括 CPU、内存、磁盘和网络趋势。指标采集数据用于本机运维，不是外部可用性 SLA。

推荐排查方式

1. 记录异常发生时间。
2. 查看同一窗口的资源趋势。
3. 查看服务或容器状态。
4. 查询错误前后的日志。
5. 实施最小变更。
6. 返回趋势和日志验证。

备份只有在能够恢复时才有价值。NodeXA 支持平台数据、MySQL 逻辑备份以及网站相关备份，不同类型的覆盖范围不同。

创建备份

1. 选择备份类型和目标。
2. 查看包含项、排除项和预计位置。
3. 确认磁盘空间和权限。
4. 创建备份。
5. 记录校验值、版本与主密钥要求。
6. 将重要备份复制到另一存储位置。

恢复前

• 确认备份来源、版本和校验值。
• 记录当前 NodeXA 版本。
• 备份当前状态。
• 确认匹配的 Secret 主密钥可用。
• 选择维护窗口并准备替代访问方式。
• 了解恢复会覆盖哪些对象。

网站恢复

网站配置恢复先进入草稿，不自动写入生效 Caddy 配置。检查域名、路径、上游、证书引用后再应用。

网站备份包含站点配置、静态内容、手动证书与 Caddy 数据（自动证书与 TLS 私钥）；包含 Caddy 数据时备份会标注敏感警告。恢复时注意私钥保护与备份版本一致性。

数据库恢复

MySQL 使用逻辑备份时，确认目标实例、字符集、权限和可用空间。先在隔离环境试恢复，验证表数量和关键数据，再计划生产恢复。

验证

• NodeXA 可启动并登录。
• 关键设置、用户和审计存在。
• 网站配置可渲染并通过 Caddy 校验。
• Secret 可解密。
• 应用和数据库健康。
• 新备份可再次创建。

完整灾难恢复见安全恢复。

告警用于把状态变化发送到明确的通知渠道，巡检聚合安全扫描和风险发现。

告警

创建告警时明确：

• 数据来源。
• 阈值和持续时间。
• 恢复条件。
• 通知渠道。
• 冷却或去重策略。
• 接收人和处理说明。

先使用测试通知验证渠道，不要在生产事故发生时才检查 Token 和网络。

巡检

巡检页聚合安全评分、最近扫描和风险发现。发现项需要结合主机用途判断，不建议对所有建议自动执行修复。

预览与限制

部分高级告警联动仍会随版本完善。页面显示的实际能力和状态是当前依据，不要根据路线规划配置不存在的自动化。

安全页面展示主机安全状态、最近扫描、风险发现和事件。安全评分用于排序处理，不是安全证明。

启用扫描

主机安全扫描由配置开关控制。未启用时页面会明确提示，不会生成虚构分数。

阅读评分

优先处理：

1. 可能导致远程访问或权限提升的高风险项。
2. 已经发生的异常登录或安全事件。
3. 防火墙、SSH 和更新的基础配置问题。
4. 中低风险加固项。

处理发现

每项发现应包含证据、影响和建议。执行变更后重新扫描，并检查服务、网络和登录方式仍然正常。

漏洞页面

漏洞聚合仍处于预览阶段。当前安全评分不等于完整的 CVE、依赖和供应链扫描结果。

防火墙页面读取 UFW 状态和规则，并对启用、停用与规则变更提供受控操作。

变更前

• 确认当前管理连接使用的端口。
• 保留另一个已验证的登录会话。
• 确认云安全组或上游防火墙。
• 记录当前 UFW 状态和规则。
• 完成 Step-up。

安全事务

高风险变更会生成待确认事务：

1. NodeXA 应用临时变更。
2. 你从另一连接验证新规则。
3. 在有效期内确认事务。
4. 未确认或主动回滚时恢复旧状态。

规则原则

• 只开放实际使用的端口。
• 尽量限制来源网段。
• 删除规则前确认没有服务依赖。
• 应用网站证书不要求开放 NodeXA 管理端口。
• 云安全组和主机 UFW 都需检查。

回滚失败

全局出现回滚失败告警时停止继续变更，使用已有安全会话检查 ufw status verbose 和规则编号，确认当前网络状态后人工恢复。

SSH 页面展示 sshd 状态、有效配置、登录事件、暴力破解线索和 fail2ban。

修改策略前

1. 保持至少两个独立 SSH 会话。
2. 确认控制台或云厂商应急入口可用。
3. 记录当前端口和认证方式。
4. 确认新公钥可以登录。
5. 检查防火墙将放行新端口。

推荐顺序

• 先验证公钥登录。
• 再限制密码认证。
• 确认非 root 管理账号具备需要的 sudo 权限。
• 最后根据需要限制 root 登录。
• 端口变化必须与 UFW 和上游安全组同步。

安全事务

NodeXA 使用受管 drop-in 应用结构化配置，并在 reload 前检查语法。变更进入待确认事务；必须从新会话完成登录后再确认。

登录事件与 fail2ban

登录事件用于识别成功、失败和暴力尝试。fail2ban 状态需要结合 jail、封禁来源和日志使用；它不能替代强认证和网络限制。

回退

若新连接失败，在事务超时前不要确认。等待自动回滚或从安全控制台恢复原配置和 UFW 规则。

审计记录用于回答“谁在什么时间对哪个对象执行了什么操作，结果如何”。

常见记录

• 用户、密码、会话与 MFA。
• 服务、任务和软件实例。
• 文件写操作。
• 备份与恢复。
• 网站、证书和应用运行环境。
• 防火墙与 SSH 安全事务。
• 系统更新和关键设置。

查询

按时间、操作者、动作、对象和结果过滤。排查跨页面操作时可结合请求 ID 与应用日志。

隐私与 Secret

审计应该记录对象标识和结果，不记录密码、Token、证书私钥、恢复码或完整环境变量。

追溯流程

1. 固定事件时间范围。
2. 查找异常登录和会话。
3. 按对象查看变更。
4. 结合服务日志、登录事件和系统日志。
5. 保存证据副本。
6. 处理风险后记录恢复动作。

Agent 面向本机运维任务，通过明确注册的工具读取状态或执行受控操作。

使用原则

• 先读取上下文，再提出或执行操作。
• 区分只读、一般变更和高风险变更。
• 高风险操作沿用 NodeXA 的认证、审计和权限要求。
• 工具输入使用结构化参数，不拼接未校验 Shell。
• 结果包含成功、失败和可验证证据。

典型用途

• 查询主机、服务和资源状态。
• 汇总日志与监控信息。
• 定位网站、应用和证书状态。
• 辅助形成排查步骤。

操作前检查

涉及服务重启、文件写入、网络、SSH、证书或恢复时，先确认目标、影响、验证方法和回退路径。

审计

Agent 发起的关键变更应能区分工具、参数摘要、操作者和结果，但不得记录 Secret 明文。

工作流和 AI 助手当前为预览入口。页面用于表达后续方向，不应展示伪造数据或让用户误以为已经能够执行完整自动化。

工作流方向

计划用于编排可复用的触发器、条件、工具步骤和人工确认点。正式开放前需要具备：

• 版本化定义。
• 权限和 Secret 引用。
• 幂等与重试边界。
• 运行历史。
• 人工审批。
• 失败停止与补偿。

AI 助手方向

计划基于只读主机上下文回答运维与安全问题，并将任何变更转换为可检查、可确认的结构化操作。

NodeXA 的可信升级只接受内置可信公钥验证通过的发布清单，并在下载后核对 SHA-256。

升级前

1. 阅读目标版本更新日志和兼容说明。
2. 确认当前版本、配置和工作目录。
3. 创建 NodeXA 备份。
4. 确认主密钥和离线备份可用。
5. 检查磁盘空间。
6. 选择维护窗口。

控制台升级

设置中的更新页面会检查签名发布清单。应用更新需要 Step-up；配置允许时会先创建备份，再由独立 updater 原子替换二进制并重启。

手动升级

使用手动包时仍需核对签名与校验值。可以使用服务 CLI 的升级或受控替换方式，避免在运行中直接覆盖二进制。

验证

• rovia version 显示目标版本。
• 服务状态正常。
• 健康接口成功。
• 可以登录并解密 Secret。
• 网站、任务、日志和备份页面可用。
• 数据迁移没有错误。

回滚

健康检查失败时自动回滚依赖配置和环境。人工回滚前保存错误日志，恢复上一二进制和兼容数据备份，再验证服务。

排查时先保留证据，再实施最小变更。记录问题时间、NodeXA 版本、页面路径、请求 ID 和最近变更。

服务无法启动

sudo rovia status
journalctl -u rovia --no-pager -n 150
ss -lntp | grep ':8080'

检查配置语法、工作目录权限、主密钥、数据库迁移和端口冲突。

页面返回 404

• 确认后端版本包含当前前端静态产物。
• 检查反向代理是否把深层路径错误重写。
• 强制刷新并清理旧缓存。
• 直接访问 /api/v1/health 判断后端是否正常。

登录或 MFA 失败

• 检查主机和认证器时间。
• 确认账号没有输入额外空格。
• 使用合法恢复码。
• 检查会话和反向代理 Cookie 属性。
• 多次失败后等待限流窗口，不要高频尝试。

Web 终端断开

• 检查反向代理 WebSocket Upgrade。
• 检查 Origin 与可信代理。
• 确认终端票据未过期。
• 检查专用用户和 PTY 权限。
• 查看 NodeXA 日志中的请求 ID。

Docker 安装失败

• 确认发行版与版本。
• 检查 DNS、HTTP 代理、软件源和包管理锁。
• 确认没有冲突包。
• 保留完整安装日志。

证书签发失败

• HTTP-01：检查 DNS、80 端口与 challenge 路径。
• DNS-01：检查 Token 最小权限和权威 DNS 传播。
• 避免连续重试触发 CA 限流。
• 使用测试环境排查流程后再申请正式证书。

收集诊断信息

分享日志前删除 Token、Cookie、证书私钥、主密钥、真实公网地址和业务数据。只提供复现所需的最小片段。

安全恢复的目标是先控制影响，再恢复可验证的服务。不要在证据尚未保存时反复修改系统。

立即控制

若怀疑账号或主机失陷：

1. 从可信网络限制管理入口。
2. 保留云控制台或物理控制台访问。
3. 保存 NodeXA、系统、SSH 和反向代理日志。
4. 吊销异常会话和凭据。
5. 记录时间线。

恢复访问

根据实际问题选择：

• 使用 MFA 恢复码。
• 从安全控制台修复反向代理或防火墙。
• 恢复经过验证的配置和数据库备份。
• 提供匹配的 Secret 主密钥。
• 恢复上一可信二进制。

恢复验证

• 只允许预期网络访问管理界面。
• 管理员登录与 MFA 正常。
• Session 列表干净。
• Secret 可解密。
• 服务、网站、应用和任务状态正确。
• 审计和日志可查询。
• 新备份可以创建并恢复测试。

事件后

轮换密码、Token、证书和必要密钥，修补根因，更新恢复文档，并把离线备份恢复演练纳入周期任务。

命令

部分版本还提供用户或升级相关子命令，以当前二进制帮助输出为准。

install 参数

安装命令可覆盖：

• 二进制路径。
• 配置文件路径。
• 工作目录。
• 运行用户。
• 是否启用开机启动。

sudo rovia install --no-enable

获取当前帮助

rovia help
rovia version

文档与命令输出不一致时，以当前二进制输出和对应版本发布说明为准。

NodeXA 控制台使用 /api/v1 下的 HTTP API。除明确公开的健康与认证端点外，业务接口需要有效会话或对应认证。

成功响应

成功响应使用统一结构：

{
  "code": "OK",
  "message": "success",
  "data": {}
}

错误响应

错误包含稳定错误码、用户可理解消息和可选细节。客户端不应只根据中文消息判断错误类型。

{
  "code": "VALIDATION_ERROR",
  "message": "参数不合法",
  "detail": "..."
}

请求追踪

响应包含 X-Request-Id。排查失败时记录请求 ID，并结合 NodeXA 日志和审计查找同一操作。

安全

• 认证 Cookie 和 Session 不应写入日志。
• 高风险接口可能要求 Step-up。
• WebSocket 使用独立票据与 Origin 校验。
• 登录和安全接口可能限流。
• API 错误不应回显内部路径、SQL 或 Secret。