该模块的功能 #

每次启动一台服务器，都得把基础配置就位：安装待处理的更新、决定程序使用的语言、设置正确的时区、给机器命名，并确保时钟走时准确。这些任务虽小却重复，而且每一项都有自己的 Linux 命令和各自的语法。

os 模块把它们全部整合在一个统一的接口之后。它更新系统（或仅更新安全部分）并告诉你是否需要重启；启用无人值守升级，让安全更新自动应用；以幂等的方式设置 locale、时区和主机名；并管理 NTP 同步，让时间永不偏移。每个操作都可以安全地重复执行：若已处于目标状态，就不做任何改动。

开始之前

会改动某些内容的子命令（更新、设置 locale、时区、主机名或 NTP）会写入系统，需要 root 权限：请用 sudo 运行它们。仅做查询的命令（status、list、check）则不需要。

快速指南分步任务

常见任务 #

选择你想做的事。每个方案都附有写好的命令 — 只需把示例值换成你自己的，再点击复制。

查看并应用更新让安全更新自动进行设置时区和时间设置系统语言更改机器名称

1

查看并应用更新

检查有哪些待处理项，并迅速更新到最新。

先查看整体状态和哪些更新在等待处理：

终端

$ imaxe os status
$ imaxe os check

应用待处理项。如果你只想要安全更新并在需要时重启，加上相应标志：

终端

$ sudo imaxe os update --security-only --reboot-if-needed

系统已更新到最新。要了解是否还有待处理的重启，使用 imaxe os reboot-required（退出码 0 = 需要重启）。

2

让安全更新自动进行

让安全更新自动应用，无需你时时盯着。

启用无人值守升级。这会为你生成 unattended-upgrades 的配置：

终端

$ sudo imaxe os autoupdate enable

确认它已启用，以及下次执行的时间：

终端

$ imaxe os autoupdate status

从现在起，安全补丁会自动安装。想关闭它？sudo imaxe os autoupdate disable。

3

设置时区和时间

设置你的 IANA 时区，并确保时钟通过 NTP 同步。

如果你记不清时区的确切名称，先筛选一下：

终端

$ imaxe os timezone list Europe

设置时区（幂等操作）并启用时间同步：

终端

$ sudo imaxe os timezone set Europe/Madrid
$ sudo imaxe os timesync enable

机器显示正确的本地时间并保持同步。用 imaxe os timesync status 检查 NTP。

4

设置系统语言

定义 LANG，并在 locale 尚不存在时生成它。

设置系统语言。该命令会生成 locale，并在缺失时安装 locales 软件包：

终端

$ sudo imaxe os locale set es_ES.UTF-8

需要更多可用语言但不改变 LANG？单独生成它们：

终端

$ sudo imaxe os locale generate es_ES.UTF-8 en_US.UTF-8

系统以所选语言显示。用 imaxe os locale status 查看当前 LANG 及已生成的 locale。

5

更改机器名称

设置清晰的主机名，并保持 /etc/hosts 一致。

分配主机名。仅允许字母、数字和连字符，最多 63 个字符：

终端

$ sudo imaxe os hostname set web-01

名称已应用，/etc/hosts 也相应更新以保持一致。用 imaxe os hostname status 验证。

注意云环境中的主机名

如果实例由 cloud-init 管理，它可能在每次启动时重写主机名。因此 os.yml 默认将 hostname 字段留空：只有在你确定 cloud-init 不会覆盖它时才去设置。

CLI 参考命令、标志与文件

用法概要 #

用法

imaxe os <subcomando> [<acción>] [<argumento>...] [flags]

会改动系统的子命令（更新、无人值守升级、locale、时区、主机名、NTP）需要 root 权限（使用 sudo）。为任何 status 或 check 加上 --json，即可获得适合脚本处理的机器可读输出。

子命令 #

子命令	功能	操作 / 标志
status	系统更新状态的概览。	--json
update	立即应用待处理的更新。	--security-only, --reboot-if-needed
check	列出待处理的更新但不应用它们。	--json
reboot-required	指示是否有待处理的重启（退出码 0 = 是，1 = 否）。	--json
autoupdate	管理无人值守的自动更新。	enable · disable · status
locale	管理系统 locale（生成并安装所需内容）。	status · list · set · generate
timezone	显示或更改系统时区。	status · list · set
hostname	显示或更改主机名（与 /etc/hosts 保持一致）。	status · set
timesync	管理时间同步（NTP）。	status · enable · disable

参数与标志 #

参数 / 标志	类型	适用于	说明
--json	bool	status · check	将结果以结构化 JSON 输出到 `stdout`，适合脚本处理。
--security-only	bool	update	仅应用安全更新。
--reboot-if-needed	bool	update	如果系统在更新后需要重启，则自动重启。
<locale> 必填	string…	locale set · locale generate	格式为 `es_ES.UTF-8` 的 locale。在 `set` 中为一个（系统的 LANG）；在 `generate` 中为一个或多个待生成的 locale。
<zona> 必填	string	timezone set	IANA 时区，例如 `Europe/Madrid`。
<filtro>	string	timezone list	用于缩小时区列表范围的可选筛选（例如 `Europe`）。
<nuevo> 必填	string	hostname set	新主机名：小写 `a-z`、数字 `0-9` 和连字符，最多 63 个字符。

文件与路径 #

路径	内容
/etc/imaxe/os.yml	模块配置：无人值守升级、更新策略、locale、时区、主机名和 NTP。
/var/log/imaxe/os.log	每次更新和系统配置变更的结构化日志。
/etc/apt/apt.conf.d/20auto-upgrades	由 `autoupdate enable` 生成、用于启用无人值守升级的配置。
/etc/apt/apt.conf.d/50unattended-upgrades	`unattended-upgrades` 的规则（更新哪些内容、重启窗口、排除列表）。

os.yml 示例：

/etc/imaxe/os.yml

unattended:
  enabled: true
  security_only: true
  automatic_reboot: false
  automatic_reboot_time: "03:00"
  blacklist: []
update:
  default_security_only: false
locale:
  lang: es_ES.UTF-8
  generate: [es_ES.UTF-8, en_US.UTF-8]
timezone: Europe/Madrid
hostname: ""
ntp:
  enabled: true

空字段（""）表示「不要改动」：模块会让该设置保持原样。因此 hostname 默认为空 — 实例通常由 cloud-init 管理它。

退出码与日志 #

每次执行都会返回一个退出码，你可以用 echo $? 查看 — 便于在脚本中串联：

0OK操作已成功完成。

1ERR未归类的一般性错误。请查看日志。

2USAGE参数无效或缺失。

reboot-required 用退出码作为回答：0 表示「是，需要重启」，1 表示「否」。这样你就能直接在脚本中串联它，无需解析文本。

调试时实时跟踪日志：

终端

$ sudo tail -f /var/log/imaxe/os.log

故障排查 #

现象	可能原因	解决方法
出现 USAGE（退出码 2）	缺少必填参数（locale、时区或主机名），或格式无效。	查看参数表：主机名仅允许 `a-z0-9` 和连字符（≤63）。
重启后主机名又变回去了	`cloud-init` 在每次启动时重写主机名。	在 `cloud-init` 中禁用主机名管理，或将 `os.yml` 中的字段留空且不手动设置。
`locale set` 缓慢或失败	`locales` 软件包不存在，需要安装/生成。	在系统为最新状态时重试（`imaxe os update`）；模块会自动安装 `locales` 并生成 locale。
时间仍有偏差	NTP 同步已禁用。	用 `sudo imaxe os timesync enable` 启用，并用 `imaxe os timesync status` 验证。
无人值守升级未应用	这台机器从未启用过无人值守升级。	运行 `sudo imaxe os autoupdate enable` 并用 `imaxe os autoupdate status` 确认。

系统模块遇到问题了？

把「imaxe <module> status --json」的输出发给我们，我们会尽快回复你。

联系支持

让服务器的基础井然有序