first commit

README.md

@@ -0,0 +1,425 @@
+# openEuler 文档：树莓派安装指南
+
+## 安装准备
+
+### 获取安装源
+
+在开始安装之前，您需要获取 openEuler 为树莓派发布的镜像文件及其校验文件。
+
+1. 访问 [openEuler 仓库](https://repo.openeuler.org/) 网站。
+
+2. 在版本列表中点击“openEuler 24.03 LTS”，进入 openEuler 24.03 LTS 的下载页面。
+
+![alt text](image.png)
+
+3. 点击“raspi_img”，进入树莓派镜像的下载列表。
+
+![alt text](image-1.png)
+
+4. 点击“openEuler-24.03-LTS-raspi-aarch64.img.xz”，将 openEuler 发布的树莓派镜像下载到本地。
+
+5. 点击“openEuler-24.03-LTS-raspi-aarch64.img.xz.sha256sum”，将 openEuler 发布的树莓派镜像的校验文件下载到本地。
+
+![alt text](image-2.png)
+
+### 镜像完整性校验
+
+1. 获取校验文件中的校验值。执行以下命令：
+
+```shell
+cat openEuler-24.03-LTS-raspi-aarch64.img.xz.sha256sum
+```
+
+2. 计算文件的 sha256 校验值。执行以下命令：
+
+```shell
+sha256sum openEuler-24.03-LTS-raspi-aarch64.img.xz
+```
+
+命令执行完成后，输出校验值。
+
+3. 对比步骤 1 和步骤 2 计算的校验值是否一致。
+
+如果校验值一致，说明下载的文件完整性没有被破坏；如果校验值不一致，则可以确认文件完整性已被破坏，需要重新获取。
+
+![alt text](image-3.png)
+
+## 安装方式
+
+要在树莓派上安装 openEuler，您需要将下载的镜像刷写到 SD 卡上。
+
+本教程基于 Linux Mint 22 系统进行，因此适用于 Linux 环境。
+
+![alt text](image-4.png)
+
+### 查看磁盘分区信息
+
+在 root 权限下执行 `fdisk -l` 命令，获取 SD 卡的磁盘信息。例如，笔者的 SD 卡对应的磁盘为 `/dev/sda`。
+
+![alt text](image-5.png)
+
+### 卸载 SD 卡挂载点
+
+1. 执行 `df -lh` 命令查看当前已挂载的卷。
+
+2. 如果 SD 卡对应的分区未挂载，则跳过该步骤。
+
+3. 如果 SD 卡对应的分区已挂载，例如笔者的 SD 卡对应的两个分区 `/dev/sda1` 和 `/dev/sda3` 已挂载，则继续下一步。
+
+![alt text](image-6.png)
+
+4. 卸载对应挂载分区。在 root 权限下执行以下命令：
+
+```shell
+# 注意：卸载的分区需要根据实际情况进行调整
+umount /dev/sda1
+umount /dev/sda3
+```
+
+5. 执行 `df -lh` 命令查看是否卸载成功。
+
+![alt text](image-7.png)
+
+### 写入 SD 卡
+
+1. 如果获取的是压缩后的镜像，需要先执行 `xz -d openEuler-{version}-raspi-aarch64.img.xz` 命令将压缩文件解压，得到 `openEuler-{version}-raspi-aarch64.img` 镜像文件；否则，跳过该步骤。
+
+![alt text](image-8.png)
+
+2. 将镜像 `openEuler-{version}-raspi-aarch64.img` 刷写入 SD 卡。在 root 权限下执行以下命令：
+
+```shell
+# 注意：将 version 替换为实际版本号，/dev/sda 替换为实际 SD 卡对应的磁盘
+# 如果提示权限不足，可以在 dd 命令前添加 sudo
+dd bs=4M if=openEuler-{version}-raspi-aarch64.img of=/dev/sda
+```
+
+> 一般情况下，将块大小设置为 4M。如果写入失败或者写入的镜像无法使用，可以尝试将块大小设置为 1M 重新写入，但设置为 1M 会比较耗时。
+
+![alt text](image-9.png)
+
+## 安装指导
+
+### 启动系统
+
+将刷写镜像后的 SD 卡插入树莓派，通电启用。
+
+### 登录系统
+
+登录树莓派有以下两种方式：
+
+1. **本地登录**
+
+   将树莓派连接到显示器（树莓派视频输出接口为 Micro HDMI）、键盘和鼠标后，启动树莓派。您将看到树莓派的启动日志输出到显示器上。待树莓派启动成功后，输入用户名（root）和密码（openeuler）进行登录。
+
+2. **SSH 远程登录**
+
+   树莓派默认采用 DHCP 方式自动获取 IP。如果树莓派连接到已知路由器，您可以登录路由器查看新增的 IP，该 IP 即为树莓派的 IP。例如，树莓派对应的 IP 为：192.168.31.109，使用命令 `ssh root@192.168.31.109` 后输入密码 openeuler，即可远程登录树莓派。
+
+   笔者使用的是 SSH 远程登录方式。
+
+   首先需要在路由器上查看树莓派的 IP 地址。笔者使用的是 tplink 路由器，访问 [tplogin.cn](http://login.cn)，然后输入管理员密码。
+
+   ![alt text](image-10.png)
+
+   点击设备管理，找到 openEuler 并点击管理。
+
+   ![alt text](image-11.png)
+
+   ![alt text](image-12.png)
+
+   找到树莓派的 IP 地址，笔者的树莓派 IP 地址为 192.168.2.102。
+
+   ![alt text](image-13.png)
+
+   在终端中输入 `ssh root@{IP}`，例如笔者输入 `ssh root@192.168.2.102`，然后输入 yes 来接收密钥，输入密码 openeuler，即可登录树莓派。
+
+   ![alt text](image-14.png)
+
+### 配置系统
+
+#### 扩展根目录分区
+
+默认根目录分区空间比较小，在使用之前，需要对分区进行扩容。
+
+请按照以下步骤扩展根目录分区：
+
+1. 在 root 权限下执行 fdisk -l 命令查看磁盘分区信息。命令和回显如下：
+
+![alt text](image-15.png)
+
+SD 卡对应盘符为 /dev/mmcblk0，包括 3 个分区，分别为
+
+1. /dev/mmcblk0p1：引导分区
+2. /dev/mmcblk0p2：交换分区
+3. /dev/mmcblk0p3：根目录分区
+
+这里我们需要将根目录分区 /dev/mmcblk0p3 进行扩容。
+
+2. 在 root 权限下执行 fdisk /dev/mmcblk0 命令进入到交互式命令行界面
+
+![alt text](image-16.png)
+
+1. 输入 p，查看分区信息。
+
+   记录分区 /dev/mmcblk0p3 的起始扇区号，即 /dev/mmcblk0p3 分区信息中 Start 列的值，示例中为 1593344。
+
+   ![alt text](image-17.png)
+
+2. 输入 d，删除分区。
+
+3. 输入 3 或直接按 Enter，删除序号为 3 的分区，即 /dev/mmcblk0p3 分区。
+
+![alt text](image-18.png)
+
+4. 输入 n，创建新的分区。
+
+5. 输入 p 或直接按 Enter，创建 Primary 类型的分区。
+
+6. 输入 3 或直接按 Enter，创建序号为 3 的分区，即 /dev/mmcblk0p3 分区。
+
+7. 输入新分区的起始扇区号，即第 1 步中记录的起始扇区号，示例中为 1593344。
+
+> 须知： 请勿直接按“Enter”或使用默认参数。
+
+8. 按 Enter，使用默认的最后一个扇区号作为新分区的终止扇区号。
+
+9. 输入 N，不修改扇区标记。
+
+10. 输入 w，保存分区设置并退出交互式命令行界面。
+
+![alt text](image-19.png)
+
+3. 在 root 权限下执行 fdisk -l 命令查看磁盘分区信息，以确保磁盘分区正确。命令和回显如下：
+
+![alt text](image-20.png)
+
+4. 在 root 权限下执行 resize2fs /dev/mmcblk0p3，增大未加载的文件系统大小。
+
+![alt text](image-21.png)
+
+5. 执行 df -lh 命令查看磁盘空间信息，以确保根目录分区已扩展。
+
+![alt text](image-22.png)
+
+> 须知： 如果根目录分区未扩展，可执行 reboot 命令重启树莓派之后再在 root 权限下执行 resize2fs /dev/mmcblk0p3。
+
+#### 连接 WIFI
+
+如果需要随身携带树莓派，可以连接 WIFI 网络。
+
+1. 查看 IP 和网卡信息
+
+```shell
+ip a
+```
+
+获取无线网卡 wlan0 信息：
+
+![alt text](image-23.png)
+
+2. 扫描可以连接的 WIFI 信息
+
+```shell
+nmcli dev wifi
+```
+
+![alt text](image-24.png)
+
+3. 连接 WIFI
+
+在 root 权限下执行 nmcli dev wifi connect SSID password PWD 命令连接 WIFI。
+
+其中，SSID 为上一步扫描到的可供连接的 WIFI 的 SSID，PWD 为对应 WIFI 的密码。例如，SSID 为 Madoka，密码为 12345678，则连接该 WIFI 命令为：nmcli dev wifi connect Madoka password 12345678，连接成功：
+
+![alt text](image-25.png)
+
+4. 查看 IP 和无线网卡信息
+
+```shell
+ip a
+```
+
+![alt text](image-26.png)
+
+连接成功后，使用同一 WIFI 网络的设备可以通过 SSH 远程登录树莓派。
+
+笔者是使用手机提供热点，树莓派和电脑连接该热点，然后从手机热点已连接设备中查看树莓派的 IP 地址，使用 SSH 远程登录树莓派。
+
+笔者树莓派连接热点后 IP 地址为 192.168.220.180，在电脑中使用 `ssh root@192.168.220.180`
+
+但是由于之前笔者电脑已经连接过树莓派，所以会提示密钥已经存在，需要删除 `~/.ssh/known_hosts` 文件中对应的树莓派密钥，然后再次连接接受密钥即可，连接密码仍为 openeuler。
+
+## iSulad 安装方法
+
+openEuler 24.03 LTS 版本默认包管理工具为 DNF，iSulad 依赖的软件包在 openEuler 24.03 LTS 版本的软件源中，可以通过 DNF 安装。
+
+首先，更新软件源：
+
+```shell
+dnf update
+```
+
+然后，安装 iSulad：
+
+```shell
+dnf install -y iSulad
+```
+
+安装完成后，在 root 权限下执行 `systemctl status isulad` 查看 iSulad 服务状态，如下图所示：
+
+![alt text](image-27.png)
+
+可以看到 iSulad 服务已启动。
+
+## Docker 安装方法
+
+同 iSulad 类似，使用 dnf 包管理工具以 root 权限运行：
+
+```shell
+dnf install -y docker
+```
+
+但是与 iSulad 不同的是，Docker 服务默认未启动，需要手动启动：
+
+```shell
+systemctl start docker
+```
+
+同时，可以设置 Docker 服务开机自启动：
+
+```shell
+systemctl enable docker
+```
+
+### 通过 Docker 应用数据库 OpenGauss
+
+1. Docker 默认使用的是国外镜像源，为了加速拉取镜像，可以设置国内镜像源，否则拉取镜像速度会很慢甚至失败
+
+创建并编辑 `/etc/docker/daemon.json` (如果文件或文件夹不存在，则需要手动创建)
+
+```shell
+# 如果没有docker文件夹
+# mkdir -p /etc/docker
+vim /etc/docker/daemon.json
+```
+
+内容为:
+
+```json
+{
+  "registry-mirrors": ["<镜像加速器地址>"]
+}
+```
+
+2. 拉取 OpenGauss 镜像，笔者使用 `enmotech/opengauss`，因为该镜像更新较快的同时引用量较高
+
+> 注意： 从此处开始，如果你的设备是树莓派 4b 或其它树莓派，需要将 `enmotech/opengauss` 替换为 `enmotech/opengauss-lite`
+>
+> 为了演示删除容器镜像，笔者先使用 `enmotech/opengauss` 镜像
+
+```shell
+docker pull enmotech/opengauss
+```
+
+![alt text](image-28.png)
+
+运行 `docker images` 可以查看已经拉取的镜像
+
+![alt text](image-29.png)
+
+拉取镜像后，根据官方文档，运行 OpenGauss 容器，可以通过 `--name` 参数指定容器名称，`-e` 参数指定环境变量，`-p` 参数指定端口映射，例如，`OpenGauss` 有环境变量 `GS_PASSWORD`，可以通过 `-e GS_PASSWORD=your_password` 指定密码，`OpenGauss` 默认端口为 `5432`，可以通过 `-p 5432:5432` 映射到宿主机端口 `5432`，运行命令如下：
+
+```shell
+docker run -d --name opengauss_container -e GS_PASSWORD=your_password -p 5432:5432 enmotech/opengauss:latest
+```
+
+但是这样生成的容器一旦被销毁，数据就会丢失，因此如果想要将数据持久化，可以通过 `-v` 参数将容器内的数据卷映射到宿主机上，例如，将容器内的 `/var/lib/opengauss` 映射到宿主机的 `/data/opengauss` ，运行命令如下：
+
+```shell
+# 根据需要将 /data/opengauss 替换为你想要的路径
+docker run -d --name opengauss_container -e GS_PASSWORD=your_password -p 5432:5432 -v /data/opengauss:/var/lib/opengauss enmotech/opengauss:latest
+```
+
+例如笔者想将 opengauss 数据库中的数据持久化在 `/root/data/opengauss`，密码设置为 `my_opengauss`，容器命名为 `container_opengauss`，则可以运行如下命令：
+
+```shell
+docker run -d --name container_opengauss -e GS_PASSWORD=my_opengauss -p 5432:5432 -v /root/data/opengauss:/var/lib/opengauss enmotech/opengauss:latest
+```
+
+![alt text](image-30.png)
+
+如果想要查看有哪些容器正在运行，可以通过 `docker ps` 命令查看
+
+然而，笔者运行`docker ps`发现没有内容显示：
+
+![alt text](image-31.png)
+
+于是，可以通过 `docker ps -a` 查看所有容器，包括正在运行的和已经停止的
+
+![alt text](image-32.png)
+
+发现容器 `container_opengauss` 已经创建，但是状态为 `Exited(1)`，并没有成功运行
+
+此时可以通过 `docker logs container_opengauss`来查看容器的日志，查看容器运行失败的原因，如果你的容器名称不是 `container_opengauss`，请将 `container_opengauss` 替换为你的容器名称
+
+![alt text](image-33.png)
+
+通过容器日志发现，容器运行失败的原因是通过环境变量设置的密码不符合要求，要求至少有一个大写和小写字符、数字和特殊字符，因此需要重新运行容器，并设置符合要求的密码
+
+同时可以通过 `docker rm container_opengauss` 删除已经创建的容器，然后重新运行容器
+
+对于某些一次性的容器（例如只使用 gcc 容器编译一次程序），可以通过 `docker run --rm` 来运行容器，容器停止后会自动删除，避免忘掉删除容器，占用过多空间
+
+此时通过 `docker ps -a` 可以看到容器已经删除
+
+![alt text](image-34.png)
+
+删除容器后，通过`docker run -d --name container_opengauss -e GS_PASSWORD=MyOpenGauss@0 -p 5432:5432 -v /root/data/opengauss:/var/lib/opengauss enmotech/opengauss:latest`重新运行容器
+
+发现这次容器已经成功运行
+
+![alt text](image-35.png)
+
+`docker` 允许通过 `docker exec` 命令进入容器内部，可以通过 `docker exec -it container_opengauss /bin/bash` 进入容器内部，然后可以通过 `psql -U postgres` 进入数据库
+
+其中，`/bin/bash` 是指通过容器内的 `/bin/bash` 进程进入容器，`-it` 参数是指交互式进入容器，`container_opengauss` 是容器名称，`psql -U postgres` 是指通过 `postgres` 用户进入数据库
+
+然而，一进入容器内部，发现容器直接报错，通过 `docker logs container_opengauss` 查看日志，发现似乎是因为树莓派 4b 的架构不支持 `opengauss`，因此无法运行
+
+![alt text](image-36.png)
+
+于是将镜像更换为 `enmotech/opengauss-lite`
+
+```shell
+docker pull enmotech/opengauss-lite
+```
+
+那么之前的`enmotech/opengauss`镜像就没用了，为了避免占用过多空间，可以通过 `docker rmi enmotech/opengauss` 删除镜像，如果你要删除其它镜像，可以通过 `docker rmi image_id` 删除（可以只填写 image_id 前几位字符，只要和其它镜像不重叠，你也可以改为容器镜像本身的名字）
+
+```shell
+docker rmi c3
+# 或者 docker rmi enmotech/opengauss
+```
+
+![alt text](image-37.png)
+
+> 注意： docker rmi 是删除镜像，docker rm 是删除容器
+
+将先前运行容器的命令修改为 `enmotech/opengauss-lite`，并重新运行容器
+
+```shell
+docker run -d --name container_opengauss -e GS_PASSWORD=MyOpenGauss@0 -p 5432:5432 -v /root/data/opengauss:/var/lib/opengauss enmotech/opengauss-lite:latest
+```
+
+此时再
+
+```shell
+docker exec -it container_opengauss /bin/bash
+```
+
+便可以成功进入容器内部：
+
+![alt text](image-38.png)
+
+之所以进入容器内部，是为了演示如何通过 `psql -U postgres` 进入数据库