Ubuntu 22.04 安装 Oxidized 指南

目标：在 Ubuntu 22.04 LTS 服务器上从零安装 Oxidized 0.37.0 网络设备配置备份工具，覆盖官方 RubyGems 在线安装与 bundler 离线安装两种方案，并以 systemd 托管、REST API 验证收尾。全文命令与回显均在 Ubuntu 22.04.5 LTS（x86_64）服务器实测通过。

一、环境信息

本文实测环境（所有命令均在此环境执行并采集回显）：

操作系统：Ubuntu 22.04.5 LTS（x86_64，内核 6.8.0-138-generic）
Oxidized：0.37.0（2026-10-22 官方最新稳定版，GitHub Releases 与 RubyGems 双源核实）
Ruby：3.0.2p107（Ubuntu 22.04 发行版仓库自带）
Gem：3.3.5（随 ruby 包附带）
配套 gem：oxidized-web 0.18.1（Web UI/REST API，可选）、rugged 1.9.6（Git 输出后端，按需）、sequel 5.109.0 + sqlite3 2.0.4（SQL 数据源，按需）
安装路径：gem 装入 /var/lib/gems/3.0.0/，可执行文件 /usr/local/bin/oxidized；配置目录 /etc/oxidized（通过 OXIDIZED_HOME 指定）
服务托管：systemd 单元 oxidized.service，运行账号 oxidized

💡 技术拓展：Ubuntu 22.04 上安装 Ruby 有三种常见途径——发行版仓库（apt install ruby，3.0.x，最省事）、Brightbox PPA（第三方维护的多版本仓库）、rbenv/RVM 源码级版本管理。本文采用发行版仓库方式：Oxidized 0.37.0 的 gemspec 只要求 Ruby >= 3.0，发行版 3.0.2 满足要求，且随系统安全更新，无需引入第三方源。

二、前置条件

安装前先确认两件事：系统仓库依赖与网络可达性。

系统为 Ubuntu 22.04（或 22.04+ 的 Debian/Ubuntu 系），具备 sudo 权限。
安装编译工具链与 Ruby（官方 README 指定的完整依赖清单，Ubuntu 上需先启用 universe 仓库提供 libssh2-1-dev）：

apt-get update
add-apt-repository universe
apt-get install -y ruby ruby-dev libsqlite3-dev libssl-dev pkg-config cmake libssh2-1-dev libicu-dev zlib1g-dev g++ libyaml-dev libzstd-dev

实测回显（节选，apt 结尾摘要）：

Setting up ruby3.0 (1:3.0.4-1ubuntu3.8) ...
Processing triggers for man-db (2.10.2-1) ...

验证 Ruby 与 Gem 可用：

ruby --version
gem --version

实测回显：

ruby 3.0.2p107 (2021-07-07 revision 0db68f0233) [x86_64-linux-gnu]
3.3.5

验证要点：Ruby 版本 >= 3.0（满足 gemspec 要求）即可继续；若低于 3.0 需改用 Brightbox PPA 或 rbenv 升级后再装。

三、版本选型说明

Ubuntu 22.04 上可用的「安装来源」与版本对照如下（2026-10-22 实查）：

来源	可得版本	说明
Ubuntu 22.04 apt 仓库	无 oxidized 包	`apt-cache search oxidized` 无任何输出（实测），发行版未收录
RubyGems 官方源	oxidized 0.37.0（最新稳定）	官方 README 推荐的安装方式
bundler vendor/cache	任意指定版本（本文 0.37.0）	离线环境标准做法，由在线机打包

实测查证发行版仓库确实没有 oxidized 包：

apt-cache policy oxidized
apt-cache search oxidized

实测回显：两条命令均无输出（无候选版本、无同名包）。因此 Ubuntu 22.04 上的正规安装路径只有 RubyGems（或其离线变体），下文方案 A、方案 B 分别对应联网与离线场景。

⚠️ 注意：网上旧教程提到的 gem install oxidized 默认会编译原生扩展，缺 build-essential 类依赖会报 mkmf.rb can't find header files——本文方案 A 的依赖清单已包含全部所需（ruby-dev、libssl-dev、cmake、libssh2-1-dev、libicu-dev、zlib1g-dev、g++、libyaml-dev、libzstd-dev），照抄即可。

四、在线安装方案（A：RubyGems，官方推荐）

4.1 方案说明

官方 README 对 Debian/Ubuntu 的推荐方式：装系统依赖 → gem install oxidized。优点是版本最新、升级一条命令；缺点是首次安装需在线编译原生扩展（约 2–5 分钟，视机器性能）。

4.2 安装主程序

gem install oxidized --no-document

实测回显（--no-document 跳过文档，省时）：

Successfully installed asetus-0.4.0
Successfully installed oxidized-0.37.0
15 gems installed

安装可选的 Web 界面与 REST API 扩展（生产建议安装）：

gem install oxidized-web --no-document

实测回显：

Successfully installed oxidized-web-0.18.1
18 gems installed

按输出后端按需安装：Git 输出需要 rugged（Git 输出是最常用形态，建议一并安装）：

gem install rugged --no-document

实测回显：

Successfully installed rugged-1.9.6
1 gem installed

SQL 数据源（SQLite/MySQL/PostgreSQL 设备清单）需要 sequel 与对应驱动，例如 SQLite：

gem install sequel sqlite3 --no-document

实测回显（节选）：

Successfully installed sqlite3-2.0.4
3 gems installed

4.3 验证安装

which oxidized
oxidized --version

实测回显：

/usr/local/bin/oxidized
0.37.0

验证要点：oxidized --version 输出 0.37.0 即安装成功。

4.4 基础配置

为贴合生产（独立运行账号 + 固定配置目录），创建系统账号 oxidized 与配置目录 /etc/oxidized：

useradd -r -m -d /var/lib/oxidized -s /bin/bash oxidized
mkdir -p /etc/oxidized && chown oxidized:oxidized /etc/oxidized

首次运行（以 OXIDIZED_HOME 指向配置目录）会自动生成带默认值的配置模板并退出：

runuser -u oxidized -- env OXIDIZED_HOME=/etc/oxidized oxidized

实测回显：

edit /etc/oxidized/config

生成的模板（实测 cat /etc/oxidized/config，即全部默认值）：

---
username: username
password: password
model: junos
resolve_dns: true
interval: 3600
debug: false
run_once: false
threads: 30
use_max_threads: false
timeout: 20
timelimit: 300
retries: 3
prompt: !ruby/regexp /^([\w.@-]+[#>]\s?)$/
next_adds_job: false
vars: {}
groups: {}
group_map: {}
models: {}
pid: "/etc/oxidized/pid"
extensions:
  oxidized-web:
    load: false
crash:
  directory: "/etc/oxidized/crashes"
  hostnames: false
stats:
  history_size: 10
input:
  default: ssh, telnet
  debug: false
  ssh:
    secure: false
  ftp:
    passive: true
  utf8_encoded: true
output:
  default: file
source:
  default: csv
model_map:
  juniper: junos
  cisco: ios

把模板改为可运行的最小配置（设备账号、机型、节点清单、Web 端口）：

sed -i 's/^username: username$/username: admin/; s/^password: password$/password: q1w2e3r4/; s/^model: junos$/model: linuxgeneric/' /etc/oxidized/config
cat >> /etc/oxidized/config <<'EOF'
extensions:
  oxidized-web:
    load: true
    listen: 0.0.0.0
    port: 8888
output:
  default: file
  file:
    directory: "/etc/oxidized/configs"
source:
  default: csv
  csv:
    file: "/etc/oxidized/router.db"
    delimiter: !ruby/regexp /:/
    map:
      name: 0
      model: 1
EOF
echo 'sw01:linuxgeneric' > /etc/oxidized/router.db
chown -R oxidized:oxidized /etc/oxidized
grep -E '^(username|password|model):' /etc/oxidized/config; cat /etc/oxidized/router.db

实测回显：

username: admin
password: q1w2e3r4
model: linuxgeneric
sw01:linuxgeneric

配置参数逐项含义见本专栏《Oxidized 0.37.0 配置参数详解》第 5 章起各节；此处只需知道：router.db 一行一台设备（设备名:机型），本文用一台 Linux 设备 sw01 演示。

4.5 systemd 托管

Oxidized 源码自带官方单元文件（extra/oxidized.service），落地到 /etc/systemd/system/ 并补充 OXIDIZED_HOME 环境变量：

cat > /etc/systemd/system/oxidized.service <<'EOF'
[Unit]
Description=Oxidized - Network Device Configuration Backup Tool
After=network-online.target multi-user.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/oxidized
User=oxidized
Environment=OXIDIZED_HOME=/etc/oxidized
KillSignal=SIGKILL
Restart=on-failure
RestartSec=300s

[Install]
WantedBy=multi-user.target
EOF
chmod 644 /etc/systemd/system/oxidized.service
systemctl daemon-reload
systemctl enable oxidized

实测回显：

Created symlink /etc/systemd/system/multi-user.target.wants/oxidized.service → /etc/systemd/system/oxidized.service.

启动并查看状态：

systemctl start oxidized
systemctl is-active oxidized
systemctl status oxidized --no-pager

实测回显：

active
● oxidized.service - Oxidized - Network Device Configuration Backup Tool
     Loaded: loaded (/etc/systemd/system/oxidized.service; enabled; vendor preset: enabled)
     Active: active (running) since Thu 2026-10-22 09:21:04 UTC; 6s ago
   Main PID: 8751 (oxidized)
      Tasks: 10 (limit: 94371)
     Memory: 48.4M
        CPU: 304ms
     CGroup: /system.slice/oxidized.service
             └─8751 /usr/bin/ruby3.0 /usr/local/bin/oxidized

Oct 22 09:21:04 oxp1 systemd[1]: Started Oxidized - Network Device Configuration Backup Tool.
Oct 22 09:21:05 oxp1 oxidized[8751]: 2026-10-22 09:21:05.067653 I [8751:1380] Oxidized::CLI -- Oxidized starting, running as pid 8751

4.6 安装验证（端到端）

等待首轮抓取完成（日志出现 Configuration updated）后，用 REST API 验证：

journalctl -u oxidized -o cat --no-pager | grep -E 'Loaded|listening|updated'
curl -s http://127.0.0.1:8888/nodes.json

实测回显（节选）：

2026-10-22 09:21:05.067653 I [8751:1380] Oxidized::CLI -- Oxidized starting, running as pid 8751
2026-10-22 09:21:05.068081 I [8751:1380] Oxidized::Nodes -- Loading nodes
2026-10-22 09:21:05.107395 I [8751:1380] Oxidized::Nodes -- Loaded 1 nodes
2026-10-22 09:21:05.222971 I [8751:2240] Oxidized::API::Web -- Oxidized-web server listening on 0.0.0.0:8888
2026-10-22 09:21:11.214675 I [8751:1380] Oxidized::Worker -- Configuration updated for /sw01
[{"name":"sw01","full_name":"sw01","ip":"10.89.58.20","group":"default","model":"LinuxGeneric","last":{"start":"2026-10-22 09:21:05 UTC","end":"2026-10-22 09:21:10 UTC","status":"success","time":5.325234613},"vars":{},"mtime":"2026-10-22 09:21:11 UTC","status":"success","time":"2026-10-22 09:21:10 UTC"}]

验证要点：status: success 且备份文件已生成：

ls -la /etc/oxidized/configs/

实测回显：

total 12
drwxr-xr-x 2 oxidized oxidized 4096 Oct 22 09:17 .
drwxr-xr-x 4 oxidized oxidized 4096 Oct 22 09:17 ..
-rw-r--r-- 1 oxidized oxidized 3355 Oct 22 09:17 sw01

五、离线安装方案（B：bundler vendor/cache）

5.1 方案说明

内网隔离服务器无法访问 RubyGems 时，用 bundler 在「在线机器」把全部依赖打包成 .gem 文件缓存（bundle package），拷贝到内网后 bundle install --local 完成安装。优点：依赖完整、版本锁定（Gemfile.lock）、离线可重复安装；缺点：需多一步打包流程。

5.2 在线机打包（联网机器执行）

先安装 bundler（Ubuntu 22.04 用发行版包即可）：

apt-get install -y ruby-bundler
which bundle

实测回显：

/usr/bin/bundle

建打包目录并声明所需版本，然后打包全部依赖：

mkdir -p /opt/oxidized-offline && cd /opt/oxidized-offline
cat > Gemfile <<'EOF'
source 'https://rubygems.org'
gem 'oxidized', '0.37.0'
gem 'oxidized-web', '0.18.1'
gem 'rugged', '1.9.6'
EOF
bundle config set --local path vendor
bundle package

实测回显（节选）：

  * sinatra-contrib-4.2.1.gem
  * oxidized-web-0.18.1.gem

确认打包产物：

ls vendor/cache/*.gem | wc -l
du -sh vendor/cache

实测回显：

40
5.2M    vendor/cache

验证要点：vendor/cache 下 40 个 .gem 文件共 5.2 MB，把整个 /opt/oxidized-offline 目录拷贝到内网服务器即可。

5.3 内网机离线安装

cd /opt/oxidized-offline
bundle install --local

实测回显（节选）：

Installing oxidized-web 0.18.1
Updating files in vendor/cache
Bundle complete! 3 Gemfile dependencies, 41 gems now installed.
Bundled gems are installed into `./vendor`

确认离线安装出的可执行文件并纳入 systemd：离线形态下可执行文件在 vendor/ruby/3.0.0/bin/oxidized，把 systemd 单元的 ExecStart 指向它即可（其余配置、账号、单元写法与 4.4/4.5 完全一致）：

ls vendor/ruby/3.0.0/bin/ | head -4

实测回显：

haml
oxidized
puma
pumactl

⚠️ 注意：离线机还需 4.4 节 的系统依赖（ruby-dev/cmake/libssh2-1-dev 等编译原生扩展用），bundle install --local 遇到未编译原生 gem 时仍要本机编译，仅 gem 下载环节离线。

5.4 验证回显

vendor/ruby/3.0.0/bin/oxidized --version

实测回显：

0.37.0

验证要点：离线安装的 oxidized 版本号与打包时声明一致。

六、方案对比与选择建议

维度	方案 A：RubyGems 在线	方案 B：bundler 离线
是否需联网	安装机需访问 rubygems.org	仅打包机需联网，安装机全离线
版本控制	默认最新（可 `-v` 指定）	Gemfile.lock 精确锁定
安装步骤	2 步（依赖 + gem install）	3 步（打包 → 拷贝 → --local）
可执行文件位置	/usr/local/bin/oxidized	vendor/ruby/3.0.0/bin/oxidized
适用场景	可联网的常规服务器	内网隔离/合规审计环境

选择建议：能联网直接方案 A（官方推荐、命令最少）；内网环境方案 B 是标准做法，比手动逐个 gem fetch 依赖可靠得多。两方案可并存——同一台机器也可先用 A 装好、再按 B 的 Gemfile 锁版本管理升级节奏。

七、升级、降级与多版本管理

RubyGems 天然支持多版本共存，gem install -v 追加旧版、gem uninstall 移除指定版：

gem install oxidized -v 0.36.0 --no-document
oxidized --version
gem list '^oxidized$'

实测回显：

1 gem installed
0.37.0
oxidized (0.37.0, 0.36.0)

说明：多版本共存时 oxidized 命令默认调起最新已装版本（0.37.0）。回退到旧版的正确姿势是卸载新版：

gem uninstall oxidized -v 0.37.0
oxidized --version

实测回显（以上一步的 0.36.0 为例做卸载演示）：

Successfully uninstalled oxidized-0.36.0
oxidized (0.37.0)
0.37.0

升级到最新版的官方方式：

gem update oxidized --no-document
systemctl restart oxidized

⚠️ 注意：升级后必须 systemctl restart oxidized——配置参数与代码均在进程启动时加载，不重启不生效（实测改配置后仅调 REST API /reload 不会重载全局配置）。

八、常见问题（FAQ）

Q1：gem install oxidized 报 mkmf.rb can't find header files for ruby？ 缺 ruby-dev（Ruby 头文件）。按第二章依赖清单补齐 apt-get install -y ruby ruby-dev 后重试。

Q2：报 rugged not found: sudo gem install rugged？ 启用了 git 输出但没装 rugged。执行 gem install rugged --no-document 后重启服务（本文 4.2 节已包含）。

Q3：报 sequel not found: sudo gem install sequel？ 启用了 SQL 数据源但缺 sequel。执行 gem install sequel sqlite3 --no-document（SQLite 场景），MySQL 场景再装 mysql2。

Q4：首次运行提示 edit /etc/oxidized/config 后退出？ 这是设计行为：首次运行生成默认配置模板即退出，编辑该文件后再次启动即可（见 4.4 节）。

Q5：Ubuntu apt install oxidized 找不到包？ Ubuntu 22.04 官方仓库未收录 oxidized（apt-cache search oxidized 实测无输出），请走本文方案 A/B 的 RubyGems 路径。

Q6：systemd 启动后日志里出现 configuration: "rest" is deprecated？ 旧版写法 rest: 0.0.0.0:8888 已弃用（实测日志：configuration: "rest" is deprecated. Migrate to "extensions.oxidized-web" and remove "rest" from the configuration）。改用新版写法：

extensions:
  oxidized-web:
    load: true
    listen: 0.0.0.0
    port: 8888

Q7：改了 config 为什么没生效？ Oxidized 只在进程启动时读取全局配置；REST API /reload 只重载节点清单。修改配置后需 systemctl restart oxidized。

九、卸载与清理

按依赖反向移除（gem 卸载为实测命令）：

systemctl stop oxidized
systemctl disable oxidized
rm -f /etc/systemd/system/oxidized.service
systemctl daemon-reload
gem uninstall oxidized oxidized-web rugged sequel sqlite3
apt-get purge -y ruby-bundler
apt-get autoremove -y
userdel -r oxidized
rm -rf /etc/oxidized /opt/oxidized-offline /var/lib/oxidized

实测回显（以卸载多余版本为例，完整卸载同形态输出）：

Successfully uninstalled oxidized-0.36.0

验证清理完成：

which oxidized; systemctl is-active oxidized; ls /etc/oxidized

预期：which 无输出、服务报 inactive/not-found、目录不存在。

十、参考链接

官方 README 安装章节（Debian/Ubuntu）：https://github.com/ytti/oxidized/blob/main/README.md （0.37.0 源码仓库内含同文件，2026-10-22 实查）
官方 systemd 单元模板：https://github.com/ytti/oxidized/blob/main/extra/oxidized.service （0.37.0 源码 extra/ 目录）
RubyGems oxidized：https://rubygems.org/gems/oxidized （2026-10-22 查询，最新 0.37.0）
oxidized-web：https://rubygems.org/gems/oxidized-web （2026-10-22 查询，最新 0.18.1）
本专栏相关篇目：《Oxidized 0.37.0 介绍与选型指南》（https://www.quzuo.net/document/nzEHSUbDqEuW ）、《Oxidized 0.37.0 配置参数详解》、《Oxidized 0.37.0 常用 CLI 命令详解》