# xuanwan

**Repository Path**: OpenCloudOS/xuanwan

## Basic Information

- **Project Name**: xuanwan
- **Description**: 玄湾系统是一款基于OpenCloudOS的镜像构建系统，主要用于打造轻量化的操作系统。特点：在基于已有rpm包的同时，并可以对特定的软件进行定制化改动。
- **Primary Language**: Shell
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 7
- **Forks**: 9
- **Created**: 2024-03-01
- **Last Updated**: 2025-09-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: xuanwan

## README

玄湾OS
=================

玄湾OS是云原生OS的重要组件之一，聚焦于镜像的构建和升级。常规的OS镜像一般是通过Linux发行版衍生而来，在云原生场景下，具有体积臃肿、版本零散、攻击面广等不足。
为了解决传统的镜像构建和升级带来的弊端，社区研发开源了面向云原生场景的玄湾OS。


# 整体架构
玄湾OS是一款启动速度快和资源占用少，并且集成Kernel、Linux发行版和容器运行时为一体，意在为使用者提供一个专为容器安全运行的轻量级云原生操作系统。
主要包括构建系统、升级管理、配置管理等模块，介绍如下：

- 构建系统: 玄湾可以根据不同产品需求，可配置其包含的组件。组件可以来自指定软件仓库，也可以通过源代码编译产生。组件分为：基础组件（无需配置）和产品组件;
- 升级管理：玄湾提供快速升级机制以及异常版本回退机制，并且基于overlayfs实现的只读根文件系统A/B盘方式升级，同时提供受控可供用户安装的隔离空间。既防止了系统的碎片化，又保证了一定的灵活性;
- 配置管理(TODO)：配置管理模块主要对关键配置进行集中式、git 化管理，实现配置监控、异常变更告警等；
- 运维管理：运维容器主要提供 sshd 服务及调测工具，方便用户登录调测主机；
![alt text](assets/figures/XuanwanOS-arch.png)

玄湾OS不仅仅解决了传统容器镜像的弊端，而且还引入了一些新的特性，如下：

1. 轻量化:玄湾OS内冗余应用和冗余库较少，只包含必要的基础库。同时在构建时是以rpm/yum作为包管理机制来管理所有组件以及解决依赖,但是构建成镜像后就完全去掉了包管理器,这样大大减少了资源的占用.
2. 安全性:玄湾OS根文件系统默认只读，并能控制客户登录，且登录的客户仅能操作部分目录（overlay目录）。另外，玄湾OS内的基础组件将逐渐切换到rust语言，并能充分利用rust的内存安全特性。
3. 统一配置:为了方便客户使用，玄湾OS将容器环境需要的内容全部整合到一起，配置统一无差异，不会出现配置满天飞的情况。
4. 内核更新:玄湾OS支持主备镜像升级/回退，可以有效解决因磁盘或电源异常导致的宕机问题。
5. 内核优化:玄湾OS优化了内核组件，提升了系统启动速度，系统内核启动完成仅需1s。
6. 构建环境安全:玄湾OS的构建是采用容器环境隔离的方式来进行，因此，不影响构建系统本身。

# 模块介绍

## 构建系统
xbuildsys为构建系统模块，可生成玄湾OS的qcow2、rootfs、iso等格式文件，支持虚拟机、服务器部署。
xbuildsys在编译时会搭建本地repo源，其中包括dnf直接下载rpm包，本地定制rpm包(定制化内核、启动流程优化、自研云组件等)，即加速镜像构建、又能满足定制化需求。
构建时，rpm包下载、编译、镜像生成等操作，均在容器中进行，以屏蔽环境差异。主要步骤如下：
 - 构建环境准备，检查编译工具；
 - 生成容器镜像，用于下载、编译rpm包；
 - dnf下载rpm包；
 - 编译定制rpm包；
 - 编译产品，生成镜像；

此外，xbuildsys 还支持构建不同产品镜像，采用"通用配置+定制化配置"组合的方式，便于配置不同产品镜像的构建。
通过修改Yum源及配置文件等即可实现，具体构建指导见文档：[xbuildsys构建文档](https://gitee.com/OpenCloudOS/xuanwan/blob/master/xbuildsys/README.md)。

注：iso构建为可选项，使用指导见文档：[服务器版本指导](https://doc.weixin.qq.com/doc/w3_AfsAmQZUAB0N30kGOm4QiGq0FuzUB?scode=AJEAIQdfAAok7gZBCoAQAAUAaIANI)。

## 升级管理
os-update-operator为升级管理模块，基于 Operator 框架实现了 k8s 直接管理基础OS的升级/回滚，通过主备双分区快速切换，实现原子更新、快速回滚。
升级管理主要组件如下：

- up-manager：玄湾OS管理器，用于更新k8s集群中云原生OS实例。主要实现调谐逻辑，持续监听所有 node 节点的容器 OS 版本信息。当预期状态发生变化时，滚动式下发玄湾 OS 升级/回退任务。
- up-proxy：容器化部署在玄湾 OS node 节点，与 kube-apiserver 通信，对接升级/回滚任务，调用 up-executor 执行 node 节点 OS 升级/回滚任务。
- up-executor：直接运行于玄湾 OS 实例中，执行具体升级任务，包括下载从镜像服务器下载云原生OS镜像，将镜像写入待升级分区，设置分区升级元数据以及执行系统 reboot 等任务。 

此外，升级管理还支持范围升级、分批次灰度升级等，部分场景支持自动重试、暂停升级等。
部署及使用见：[升级管理用户文档](https://gitee.com/OpenCloudOS/xuanwan/blob/master/os-update-operator/ReadMe-user.md)。


## 配置管理
配置管理模块主要对关键配置进行集中式、git 化管理，实现关键配置监控、异常变更告警并恢复；非关键配置监控、记录变更日志。
更多功能敬请期待...

## 运维管理
Admin-container：运维容器组件，云原生OS不提供sshd服务，需要调测时，可通过运维容器登录，按需启动。运维容器具有privilege权限，提供sshd服务以及必要的调测工具。