# xuanwan

**Repository Path**: itwennet/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**: 0
- **Forks**: 9
- **Created**: 2024-03-25
- **Last Updated**: 2024-10-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

玄湾系统
=================

# 功能介绍
玄湾OS是云原生OS的重要组件之一。玄湾OS项目聚焦于镜像的构建和升级。常规的OS镜像一般是通过Linux发行版衍生而来，在云原生场景下，具有体积臃肿、版本零散、攻击面广等不足。玄湾OS项目的引入，就是为了解决传统的镜像构建和升级带来的弊端。如下是玄湾功能分类：



- 构建系统: 玄湾可以根据不同产品需求，可配置其包含的组件。组件可以来自指定软件仓库，也可以通过源代码编译产生。组件分为：基础组件（无需配置）和产品组件;
- 升级系统： 玄湾提供快速升级机制以及异常版本回退机制，并且基于overlayfs实现的只读根文件系统A/B盘方式升级，同时提供受控可供用户安装的隔离空间。既防止了系统的碎片化，又保证了一定的灵活性;


# 功能特点
玄湾OS是一款启动速度快和资源占用少，并且集成Kernel、Linux发行版和容器运行时为一体，意在为使用者提供一个专为容器安全运行的轻量级云原生操作系统。
然而，玄湾OS不仅仅解决了传统容器镜像的弊端，而且还引入了一些新的特性。玄湾OS将拥有如下几个特性，

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


# 玄湾OS构建

## 构建准备

1.安装 git和git lfs
```
dnf -y install git git-lfs
```
2.初始化git lfs
```
git lfs install
```
3.安装docker-buildx
```
dnf -y install https://mirrors.opencloudos.tech/epol/9/Everything/x86_64/os/Packages/docker-buildx-0.11.2-1.oc9.x86_64.rpm
```
4.下载玄湾系统
```
git clone https://gitee.com/OpenCloudOS/xuanwan.git
```

## 环境安装

构建前，需执行./prepare.sh或手动安装如下工具：

1.安装 docker-ce软件包
```
dnf -y install docker-ce
```
2.安装 cargo软件包
```
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```
3.安装 cargo-make包
```
cargo install cargo-make
```
4.安装 toml-cli包
```
cargo install toml-cli
```
5.将 cargo添加到环境变量
```
source $HOME/.cargo/env
```

## 玄湾OS
1.构建oc镜像
```
cargo make
```
2.清除oc镜像
```
cargo make clean
```

```
注：cargo make -e TENCENT_TARGET=xxxx可以编译指定的产品镜像，默认是oc9。
```

3.编译生成的镜像的命名规则为
```
产品名+kernel版本号+玄湾编译时间.img
```
例如： oc9-6.6.6-2401.0.1-{timestamp}.img

# 自定义产品

玄湾可以通过修改targets目录下的文件,来增加自定义产品,具体请参考
```
targets/README.md
```

# 自定义应用包

玄湾可以通过修改packages目录下的文件,来增加自定义应用包,具体请参考
```
packages/README.md
```

# 注意事项

1.当编译过程中，如果出现空间不足，则需要用如下命令，清理一下docker磁盘：
```
docker system prune -a
```

2.在编译C文件的时候,如果有依赖第三方库,此时的第三方库是被安装到%{_cross_sysroot}目录,因此需要在编译的时候添加CFLAGS/LDFLAGS,如下:
```
CFLAGS="-I%{_cross_sysroot}/usr/include -L%{_cross_sysroot}/usr/lib64"
```

3.当在镜像内新增安装包或者文件时，需要修改targets/<product>/Cargo.toml调整镜像大小，否则会出现镜像空间不足的情况。
```
打开Cargo.toml，找到image-size， 并修改为对应的大小。
```

4.修改packages/< package >/Cargo.toml文件后，需要执行
```
cd packages; cargo update; cd packages

注： 不执行，会出现error: the lock file packages/Cargo.lock needs to be updated but --locked was passed to prevent this
```

5.出现错误 ERROR: failed to do request: Head "https://registry-1.docker.io/v2/docker/dockerfile/manifests/1.1.3-experimental": net/http: TLS handshake timeout
```
打开/etc/docker/daemon.json文件,修改为如下(如果不存在,需要创建一个新的)
{
    "experimental": false,
    "insecure-registries": [
        "mirrors.tencent.com", // 或者这里修改成其他可用mirrors
    ]
}
修改后执行systemctl restart docker,再重新执行cargo make即可.
```

# 待新增功能（TODO）
1、增加镜像主备升级功能（A/B盘）；