add new docs: orbstack

docs/ide/assets/kwdb.yaml

@@ -0,0 +1,93 @@
+#cloud-config
+# 配置阿里云 apt 源（自动区分 amd64/其他架构，amd64 用 ubuntu 源，非 amd64 用 ubuntu-ports 源）
+apt:
+  primary:
+    - arches: [amd64]
+      uri: http://mirrors.aliyun.com/ubuntu/
+    - arches: [arm64, default]  # arm64 及其他架构统一使用 ubuntu-ports 源
+      uri: http://mirrors.aliyun.com/ubuntu-ports/
+  sources:
+    # amd64 架构专属源（ubuntu 仓库）
+    aliyun-amd64-main:
+      source: "deb [arch=amd64] http://mirrors.aliyun.com/ubuntu/ jammy main restricted universe multiverse"
+      keyid: "3B4FE6ACC0B21F32"
+    aliyun-amd64-updates:
+      source: "deb [arch=amd64] http://mirrors.aliyun.com/ubuntu/ jammy-updates main restricted universe multiverse"
+    aliyun-amd64-security:
+      source: "deb [arch=amd64] http://mirrors.aliyun.com/ubuntu/ jammy-security main restricted universe multiverse"
+
+    # 非 amd64 架构专属源（ubuntu-ports 仓库，适配 arm64 等）
+    aliyun-ports-main:
+      source: "deb [arch=arm64] http://mirrors.aliyun.com/ubuntu-ports/ jammy main restricted universe multiverse"
+      keyid: "3B4FE6ACC0B21F32"
+    aliyun-ports-updates:
+      source: "deb [arch=arm64] http://mirrors.aliyun.com/ubuntu-ports/ jammy-updates main restricted universe multiverse"
+    aliyun-ports-security:
+      source: "deb [arch=arm64] http://mirrors.aliyun.com/ubuntu-ports/ jammy-security main restricted universe multiverse"
+  update: true
+  upgrade: true  # 自动升级系统包，确保依赖兼容性
+
+# 安装编译和运行 KWDB 所需的依赖包（apt 自动匹配架构对应的包版本）
+packages:
+  - ca-certificates
+  - git
+  - build-essential
+  - autoconf
+  - automake
+  - libtool
+  - checkinstall
+  - dpkg-dev
+  - devscripts
+  - libssl-dev
+  - libprotobuf-dev
+  - protobuf-compiler
+  - libprotoc-dev
+  - liblzma-dev
+  - libncurses5-dev
+  - libgflags-dev
+  - liblz4-dev
+  - geos
+  - xz-utils
+  - squashfs-tools
+  - squashfuse
+  - openssl
+  - wget
+  - tree
+  - gnupg2  # 用于导入 GPG 密钥，解决源验证问题
+
+runcmd:
+  - |
+    ARCH=$(uname -m)
+    if [ "$ARCH" = "x86_64" ]; then
+      echo "amd64" > /tmp/go_arch.txt
+      echo "x86_64" > /tmp/cmake_arch.txt
+    elif [ "$ARCH" = "aarch64" ]; then
+      echo "arm64" > /tmp/go_arch.txt
+      echo "aarch64" > /tmp/cmake_arch.txt
+    else
+      echo "不支持的架构: $ARCH" >&2
+      exit 1
+    fi
+  - GO_ARCH=$(cat /tmp/go_arch.txt)
+  - CMAKE_ARCH=$(cat /tmp/cmake_arch.txt)
+
+  # 4. 安装 Go 1.22.5
+  - |
+      wget -q https://golang.google.cn/dl/go1.25.5.linux-${GO_ARCH}.tar.gz -O /tmp/go.tar.gz &&
+      tar -C /usr/local -xzf /tmp/go.tar.gz &&
+      rm -f /tmp/go.tar.gz
+
+
+  # 5. 安装 CMake 3.23.4
+  - |
+      wget -q https://github.com/Kitware/CMake/releases/download/v3.23.4/cmake-3.23.4-linux-${CMAKE_ARCH}.tar.gz -O /tmp/cmake.tar.gz &&
+      tar -C /usr/local -xzf /tmp/cmake.tar.gz &&
+      mv /usr/local/cmake-* /usr/local/cmake &&
+      rm -f /tmp/cmake.tar.gz
+
+
+  # 6. 配置环境变量
+  - echo 'export GOROOT=/usr/local/go' >> /etc/profile
+  - echo 'export GOPATH=/home/go' >> /etc/profile
+  - echo 'export GO111MODULE=off' >> /etc/profile
+  - echo 'export PATH=$PATH:/usr/local/go/bin:/usr/local/cmake/bin' >> /etc/profile

docs/ide/orbstack.md

@@ -0,0 +1,96 @@
+---
+title: 在 MacOS 使用 Orbstack 快速搭建 KWDB 开发环境
+id: orbstack
+sidebar_position: 3
+---
+
+本文介绍如何在 macOS 上借助 Orbstack 一键创建一台可用于 KWDB 源码编译与调试的 Ubuntu 开发环境。  
+
+## Orbstack
+
+[Orbstack](https://orbstack.dev/) 是一个功能强大的 macOS 虚拟机管理工具，支持 AMD64 和 ARM64 架构。它提供了简单的 GUI 界面，方便用户创建、管理和操作虚拟机。本文采用 Orbstack 创建一台 Ubuntu 22.04 虚拟机，用于编译和调试 KWDB 源码。
+
+### 安装
+
+1. 可以访问 [Orbstack 官网](https://orbstack.dev/)，下载并安装最新版本的 Orbstack。  
+2. 安装完成后，启动 Orbstack，它会自动配置必要的网络和存储。
+3. 或者采用 `brew install orbstack` 安装 Orbstack。
+
+## Cloud-init
+
+[Cloud-init](https://cloudinit.readthedocs.io) 是一个用于初始化 Linux 虚拟机的工具，它可以在虚拟机启动时自动执行一系列配置任务。KWDB 社区准备了一份 `kwdb.yaml` 标准配置文件，主要完成三件事：
+
+1. 配置阿里云 Ubuntu 软件源（兼容 amd64 与 arm64 架构）。  
+2. 安装编译和运行 KWDB 所需的基础依赖。  
+3. 自动安装编译需要的 Go、CMake，并设置环境变量。
+
+[下载 kwdb.yaml](./assets/kwdb.yaml)
+
+## 在 Orbstack 中创建 KWDB 开发虚拟机
+
+在 Orbstack 中创建 KWDB 开发虚拟机的步骤如下：
+
+1. 打开 Orbstack，点击创建新的 Linux 虚拟机（选择 Ubuntu 22.04 LTS 版本）。  
+2. 在高级设置（Advanced）Cloud-init user data，选择「Select User Data」，指向本地的 `kwdb.yaml`。  
+3. 点击 `Create`，首次启动时，Orbstack 会将 `kwdb.yaml` 注入到 cloud-init，系统会在后台自动：
+   - 切换阿里云软件源；
+   - 安装所有依赖包；
+   - 安装 Go、CMake；
+   - 写入环境变量。
+4. 根据网络速度，这一步可能需要数分钟，完成后虚拟机即可作为 KWDB 的开发编译环境使用。
+5. 虚拟机创建完成且启动成功后，双击 Orbstack 中的 VM 图标，即可打开一个终端窗口，登录到该 VM。
+
+!["Orbstack 创建 VM"](./img/orb.png)
+
+## 在 VM 中编译 KWDB
+
+进入 VM 后，可以参考[通过源码编译](../compilation/source-code.md)完成 KWDB 的编译和构建。以下是一个简单的示例，方便快速上手。
+
+### 下载 KWDB 源码
+
+```bash
+mkdir -p /home/go/src/gitee.com
+# 授予 /home/go 目录下的所有文件和子目录以当前用户和用户组的权限
+sudo chown -R $USER:$USER /home/go
+git clone https://gitee.com/kwdb/kwdb.git /home/go/src/gitee.com/kwbasedb #请勿修改目录路径中的 src/gitee.com/kwbasedb
+cd /home/go/src/gitee.com/kwbasedb
+git submodule update --init #适用于首次拉取代码
+git submodule update --remote
+```
+
+### 编译与安装
+
+创建构建目录并完成编译与安装：
+
+```bash
+cd /home/go/src/gitee.com/kwbasedb
+mkdir build && cd build
+# 运行 cmake 配置
+cmake .. -DCMAKE_BUILD_TYPE=Debug
+# 编译与安装
+make
+make install
+```
+
+## 配置 VS Code 远程调试
+
+用户可以直接在 VS Code 中配置远程调试，连接到 Orbstack 中的虚拟机进行调试。
+
+1. 安装 VS Code 插件：「Remote - SSH」。
+2. 打开 VS Code，点击左下角的双箭头图标。
+3. 选择「Remote SSH」，输入 Orbstack 中 VM 的 SSH 连接信息（`机器名@orb` 如果您创建的 VM 为默认虚拟机，则可直接使用 `orb`）。
+4. 按回车键后，VS Code 将自动连接至 Orbstack 中的虚拟机。
+5. 在 VS Code 中打开 KWDB 项目目录(`/home/go/src/gitee.com/kwbasedb`)，即可开始调试。
+
+![SSH Remote 连接 Orbstack](./img/orb-vscode.png)
+![连接后的界面](./img/orb-vscode-ssh.png)
+
+## 小结
+
+通过 Orbstack + cloud-init 的方式，可以将原本需要多步手动执行的环境准备过程（配置源、安装依赖、部署 Go/CMake、设置环境变量）固化在一份 YAML 文件中，实现：
+
+- **一次配置，多次复用**：在多台 Mac 或多名开发者之间共享相同的 KWDB 开发环境模板。  
+- **环境配置可审计、可版本化**：可将 `kwdb.yaml` 存放在仓库中，配合 Git 即可跟踪环境变更。  
+- **对架构友好**：自动适配 x86_64 / arm64，Apple Silicon 用户可以直接使用。
+
+后续如果 KWDB 的编译依赖或推荐工具链有更新，只需要修改 `kwdb.yaml` 并重新创建 VM，即可获得最新的开发环境。