环境配置 on 个人技术随想

Podman迁移计划

Wed, 03 Dec 2025 16:00:00 +0800

从Incus出发

在过去的一些文章里，我曾经着迷于Incus作为容器实现。

在我看来，LXC/Incus那一套共享内核同时分隔文件系统与命名空间的法则很有魅力，用来创建低开销的类虚拟机实例再适合不过了。

不过，Incus的局限也有不少，或许配置麻烦就是其中之一，需要用户学习一套全新的配置模式。

另一方面，尽管Incus已经实现OCI镜像支持，但它不直接兼容当下流行的Dockerfile + Docker Compose模式。

理论上，这两者可被Canonical生态的cloud-init脚本替代，Incus对此有非常好的支持，但改写这些脚本总归是一个调试繁琐、易出Bug的工作。

说到底，Incus更偏向于系统级容器的理念，本身就和Docker/Podman的应用级容器定位有很大差异。

如果仍然迷恋Docker风格的应用级容器，或许可以试试Podman，其绝大部分操作API或指令均和Docker相似，并默认运行在用户态，不依赖root权限级别的daemon。

安装

Podman的安装非常简单，在Debian下只需要：

`1`	`sudo apt install podman`

在Windows下安装也非常简单，可参考Podman for Windows文档。基本步骤是：

前往Github Release，下载最新版podman-installer-windows-amd64.exe文件（MSI也行；别被附件里几个不同名字的.exe骗了，它们的SHA256可能是相同的）；
开始安装，安装时可选HyperV或WSL后端，推荐WSL；
安装程序结束后，打开命令提示符，执行podman machine init，自动下载宿主虚拟机/WSL镜像并导入

若是好奇podman machine init命令干了什么，可以翻阅上面的文档，内有非常详细的介绍。

常见问题

找不到podman.sock

/run/user/<uid>/podman/podman.sock No such file or directory

请尝试：

`1`	`systemctl --user enable --now podman.socket`

容器莫名其妙自动结束

如果是以下情况：用户在保持有登录会话（如SSH）时，容器从不自动结束。而在用户关闭所有会话后一小段时间内，容器就自动退出了。

那么请尝试：

`1`	`sudo loginctl enable-linger <username>`

Windows WSL Podman设置代理

若要让基于Windows WSL的Podman使用宿主机网络代理，通常要先确定宿主机的IP，再设置环境变量。

太麻烦了，让我们用一个脚本解决这个问题吧。

使用方法：

复制以下脚本
根据自己的网络配置修改USER CONFIGURATION配置项
打开Podman WSL Machine，在WSL的/etc/profile.d/文件夹下新建个配置文件，贴进去

📝 WSL代理自动配置脚本

`/etc/profile.d/wsl-proxy.sh`

#!/bin/bash
# WSL Proxy Environment Setup Script
# Place this script in /etc/profile.d/ to auto-load proxy settings for all users
# Or source it manually

# =============================================================================
# USER CONFIGURATION SECTION
# Modify these variables according to your proxy server settings
# =============================================================================

# Proxy protocol schema (http, https, socks4, socks5)
# Default: http
PROXY_SCHEMA="${PROXY_SCHEMA:-http}"

# Proxy server hostname or IP address
# Use "{GATEWAY}" to automatically detect Windows host IP via WSL gateway
# PROXY_HOST="${PROXY_HOST:-localhost}"
PROXY_HOST="{GATEWAY}"

# Proxy server port number
# Default: 8080
PROXY_PORT="${PROXY_PORT:-8080}"

# Proxy authentication username (leave empty if not required)
# Default: empty
PROXY_USER="${PROXY_USER:-}"

# Proxy authentication password (leave empty if not required)
# Default: empty
PROXY_PASSWORD="${PROXY_PASSWORD:-}"

# Comma-separated list of addresses to bypass proxy
# These domains/IPs will not use the proxy connection
# Default: local addresses (localhost, 127.0.0.1, etc.)
PROXY_BYPASS="${PROXY_BYPASS:-localhost,127.0.0.1,::1,169.254.169.254}"

# =============================================================================
# INTERNAL FUNCTIONS
# =============================================================================

# Detect WSL gateway IP address (Windows host IP)
# This is useful when proxy server runs on Windows host
_get_wsl_gateway() {
    local gateway_ip
    # Method 1: Use ip route to find default gateway
    gateway_ip=$(ip route show default 2>/dev/null | awk '/default/ {print $3}' | head -n1)

    # Method 2: Fallback to /etc/resolv.conf nameserver (WSL2)
    if [[ -z "$gateway_ip" ]] && [[ -r /etc/resolv.conf ]]; then
        gateway_ip=$(awk '/^nameserver/ {print $2; exit}' /etc/resolv.conf)
    fi

    # Method 3: Fallback to Windows host IP pattern (WSL1)
    if [[ -z "$gateway_ip" ]]; then
        gateway_ip=$(ip route show | grep -oP 'via \K[0-9.]+' | head -n1)
    fi

    echo "$gateway_ip"
}

# Build proxy URL with optional authentication
_build_proxy_url() {
    local schema="$1"
    local host="$2"
    local port="$3"
    local user="$4"
    local password="$5"

    local url="${schema}://"

    # Add authentication if credentials provided
    if [[ -n "$user" ]]; then
        url+="${user}"
        if [[ -n "$password" ]]; then
            url+=":${password}"
        fi
        url+="@"
    fi

    # Add host and port
    url+="${host}:${port}"

    echo "$url"
}

# =============================================================================
# MAIN EXECUTION
# =============================================================================

# Resolve special {GATEWAY} keyword to actual WSL gateway IP
if [[ "$PROXY_HOST" == "{GATEWAY}" ]]; then
    PROXY_HOST=$(_get_wsl_gateway)

    # Validate gateway detection
    if [[ -z "$PROXY_HOST" ]]; then
        echo "Warning: Failed to detect WSL gateway IP. Using 'localhost' as fallback." >&2
        PROXY_HOST="localhost"
    fi
fi

# Construct full proxy URL
PROXY_URL=$(_build_proxy_url "$PROXY_SCHEMA" "$PROXY_HOST" "$PROXY_PORT" "$PROXY_USER" "$PROXY_PASSWORD")

# Export standard proxy environment variables
export HTTP_PROXY="$PROXY_URL"
export http_proxy="$PROXY_URL"
export HTTPS_PROXY="$PROXY_URL"
export https_proxy="$PROXY_URL"

# Export no-proxy settings
export NO_PROXY="$PROXY_BYPASS"
export no_proxy="$PROXY_BYPASS"

# =============================================================================
# VERBOSE OUTPUT (optional)
# Uncomment the following lines to enable debug output
# =============================================================================
# echo "WSL Proxy Configuration Loaded:"
# echo "  HTTP_PROXY:  $HTTP_PROXY"
# echo "  HTTPS_PROXY: $HTTPS_PROXY"
# echo "  NO_PROXY:    $NO_PROXY"

为容器启用N卡

通常来说，只需要首先安装NVIDIA Container Toolkit，然后使用以下命令启动容器：

`1`	`podman run --rm --gpus all docker.io/debian:trixie-slim nvidia-smi`

找不到GPU

Podman主要通过Container Device Interface (CDI)寻找调用系统中的显卡。

在安装NVIDIA Container Toolkit时，会附带一个Systemd服务nvidia-cdi-refresh.service，该服务理论上会在后台运行，自动查找系统中的N卡并刷新CDI信息。

可以通过以下命令查看N卡是否成功注册到CDI中，正常应该是这样的：

$ nvidia-ctk cdi list
INFO[0000] Found 3 CDI devices                          
nvidia.com/gpu=0
nvidia.com/gpu=GPU-12345678-1234-5678-90ab-1234567890ab
nvidia.com/gpu=all

然而，有时这一服务无法正常运行（可通过sudo systemctl status nvidia-cdi-refresh.service查看），上述服务不能正确更新CDI中的N卡注册信息，最终会导致Podman无法找到我们想要启用的显卡资源。

解决方法是，可以手动运行CDI注册命令：

`1`	`sudo nvidia-ctk cdi generate --output=/var/run/cdi/nvidia.yaml`

Podman Compose设置GPU

在docker-compose.yml文件中，可以这样定义使用GPU:

services:
  llama-server:
    image: nvidia/cuda:12.2.0-runtime-ubuntu22.04
    command: ["nvidia-smi"]
    devices:
      - nvidia.com/gpu=all

如果使用Docker Compose运行，可能会遇到错误：Error response from daemon: container create: stat nvidia.com/gpu=all: no such file or directory

解决方法非常简单：请使用Podman-Compose而不是Docker-Compose:

1
2
3

sudo apt install podman-compose

podman-compose -f docker-compose.yml up

Stable Diffusion WebUI 与 ComfyUI 安装

Sat, 09 Aug 2025 11:00:00 +0800

背景知识

Stable Diffusion WebUI (以下简称sd-webui) 和 ComfyUI 都是调用模型进行AI图片视频生成的前端，并不直接提供具体模型，原则上这两个只需其一即可完成创作。

至于优劣，原始A1111版sd-webui需要插件才能使用诸如LyCORIS之类更多的模型，在视频生产等工作上也没那么方便。ComfyUI 工作流上手则需要更多一点基础知识(我觉得其实还好)。

Stable Diffusion WebUI

系统依赖

作为一个AI任务，基础的CUDA组件自然是必不可少的，不再赘述。

在容器Debian中，可能还需要额外安装一些组件：

`1`	`sudo apt install bc google-perftools libgl1 libglib2.0-0 --no-install-recommends`

若是还有缺失的组件，莫慌，可以去https://packages.debian.org，在下面的Search the contents of packages中直接搜索缺失的库文件，安装对应的包即可，基本上不需要手动编译额外库文件。

设置网络

在安装过程中，需要加载一些网络资源，需要首先设置网络访问。

最简单的方法是设置一些PROXY，不过需要注意，要将localhost排除在外，否则webui.sh执行中会报错。

1
2
3

export NO_PROXY="localhost, 127.0.0.1, ::1"
export HTTP_PROXY=http://127.0.0.1:8888
export HTTPS_PROXY=http://127.0.0.1:8888

Python环境准备

如果没有额外需求，将一切包袱丢给webui.sh，任其自动创建所需的虚拟环境，倒也是一种懒人方法。

不过，如果期望自定义配置，那额外折腾的部分也不见得麻烦。

默认情况下，sd-webui期望的Python版本是3.10，对于比较新的系统，请考虑使用Conda等方法创建虚拟环境，并指定Python版本号。

虚拟环境激活后，sd-webui就会使用检测到的Python虚拟环境。

📝 备注

使用uv管理环境
更激进一点，如果使用uv作为pip的替代品，情况又略有不同，因为sd-webui直接通过调用pip模块安装所需组件，但uv创建的虚拟环境并没有提供pip模块。

幸好，安装过程也不麻烦，只需要不断重复运行webui.sh，把报错的pip install命令复制出来，直接改成uv pip install并执行即可。

需要注意，uv pip install没有--prefer-binary，似乎直接省略也无伤大雅。

克隆环境

`1`	`git clone https://github.com/AUTOMATIC1111/stable-diffusion-webui`

xformers

如果使用的是uv，那其实很好办，uv能自动处理xformers和torch的兼容关系，只需要在安装torch的时候一并安装即可。

`1`	`uv pip install "numpy<2" torch==2.1.2 torchvision==0.16.2 xformers --extra-index-url https://download.pytorch.org/whl/cu121`

如果使用的是pip，在无法自动匹配正确版本，或是pip动了卸载torch的心时，则需要亲自去Releases · facebookresearch/xformers · GitHub翻一下时间线，寻找和环境中torch版本匹配的小版本，然后指定版本号手动安装。

模型文件

把模型文件放到对应的models/Stable-diffusion/, models/VAE/, 还有models/Lora/文件夹下，就可以了。

一些插件

git clone "https://github.com/Physton/sd-webui-prompt-all-in-one.git" extensions/sd-webui-prompt-all-in-one
vim extensions/sd-webui-prompt-all-in-one/install.py
vim extensions/sd-webui-prompt-all-in-one/scripts/physton_prompt/packages.py
uv pip install chardet PyExecJS lxml pathos cryptography

git clone "https://github.com/DominikDoom/a1111-sd-webui-tagcomplete.git" extensions/a1111-sd-webui-tagcomplete
git clone https://github.com/CompVis/taming-transformers.git repositories/taming-transformers
git clone https://github.com/hako-mikan/sd-webui-regional-prompter.git extensions/sd-webui-regional-prompter
git clone https://github.com/pkuliyi2015/multidiffusion-upscaler-for-automatic1111.git extensions/multidiffusion-upscaler-for-automatic1111
git clone https://github.com/Mikubill/sd-webui-controlnet.git extensions/sd-webui-controlnet
git clone https://github.com/dtlnor/stable-diffusion-webui-localization-zh_CN.git extensions/stable-diffusion-webui-localization-zh_CN
git clone https://github.com/AlUlkesh/stable-diffusion-webui-images-browser.git extensions/stable-diffusion-webui-images-browser
git clone https://github.com/arenasys/stable-diffusion-webui-model-toolkit.git extensions/stable-diffusion-webui-model-toolkit

启动！

`1`	`./webui.sh`

ComfyUI

克隆环境

`1`	`git clone https://github.com/comfyanonymous/ComfyUI.git`

安装虚拟环境

如果使用的是uv，那其实很好办，uv能自动处理xformers和torch的兼容关系，只需要在安装torch的时候一并安装即可。

和 A1111 的 sd-webui 不同，ComfyUI所需的Python依赖项均已提供在requirements.txt中。

不过，默认的requirements.txt没有定义torch的版本，也没有定义xformers依赖项（xformers能大幅减少显存消耗）。所以，我们可以稍微修改一下。

ComfyUI对任意新版torch的兼容性都比较好，所以我们可以去pytorch官网，找到自己适合的torch版本，将版本信息写到requirements.txt中。同时，加上xformers依赖项。

-torch
+torch==2.5.1

-torchvision
+torchvision==0.20.1

-torchaudio
+torchaudio==2.5.1

+xformers

其他就都不用管了。直接创建一个虚拟环境，然后开装！

uv venv venv -p 3.12
source venv/bin/activate

uv pip install -r requirements.txt --extra-index-url https://download.pytorch.org/whl/cu121

模型文件复用

装完环境后，如果原本安装有sd-webui，还有一大堆模型文件，不想将模型文件再复制一份？可以直接将ComfyUI目录下的extra_model_paths.yaml.example复制一份，命名为extra_model_paths.yaml，然后按照里面的提示进行编辑，就可以指示ComfyUI前往sd-webui的目录搜索加载Stable Diffusion模型检查点了。

Nginx反向代理

如果在使用Nginx反向代理ComfyUI，并在保存工作流时遇到报错: Error storing user data file 'workflows/xxx': 405，请检查Nginx配置文件，看proxy_pass末尾是否存在斜杠。

如果存在斜杠，请将其删除。

location / {

# 这是不OK的！
-    proxy_pass         http://127.0.0.1:8188/;

# 这是OK的！
+    proxy_pass         http://127.0.0.1:8188;
}

参考: [Bug]: Save workflow 405(Method Not Allowed) When using Nginx reverse

提示词插件

手写提示词太痛苦，尤其是习惯了sd-webui的sd-webui-prompt-all-in-one插件后。

幸好，ComfyUI也有类似的插件，叫WeiLin-Comfyui-Tools。只需要git clone进ComfyUI/custom_nodes，然后根据该插件的requirements.txt补齐Python依赖，在ComfyUI中就可以使用类似的Prompt编辑器了。

当然，要是不喜欢，也可以用原来all-in-one插件的独立版本sd-webui-prompt-all-in-one-app，可以作为一个独立的Web应用运行。

Git LFS 选择性拉取文件

Tue, 05 Aug 2025 11:00:00 +0800

省流: 直接在git lfs pull中使用--include/-I和--exclude/-X选择或者排除需要拉取LFS文件。

快速下载

在Huggingface等平台上，各种模型数据库文件都会被存储为Git LFS对象。

如果不想使用Huggingface等平台提供的专用工具，如何方便地下载呢？

最简单的，无脑的方法，只需要遵照Huggingface模型页面提供的代码，克隆仓库即可

`1`	`git clone https://huggingface.co/my/model`

但是！这种方法会一次性拉取并检出所有文件，包括所有LFS文件对象。

有时，我们并不需要仓库中的所有LFS文件。比方说，一部分仓库同时提供.pth和.safetensors格式的模型权重，但我们只需要其中一种就够了。

那么，有没有更自定义一点的法子？

我们可以在克隆时忽略克隆完整的LFS对象，只保留LFS对象的指针。与此同时，正常拉取仓库中其他普通文件。

`1`	`GIT_LFS_SKIP_SMUDGE=1 git clone https://huggingface.co/my/model`

这样一来，仓库中所有非LFS对象就获取完毕了，接下来只需要按需获取LFS文件。怎么做呢？非常简单，git lfs pull提供了一个--include/-I参数：

`1`	`git lfs pull --include "*.safetensors"`

与之相对应地，还有一个--exclude/-X参数，可以指定排除的文件列表。

这样，就可以非常简单地选择性拉取一部分LFS文件，也不需要将命令拆分为多条命令，或是配置git仓库之类的。

使用uv管理Python环境

Mon, 28 Jul 2025 11:00:00 +0800

uv是什么？

请看: https://docs.astral.sh/uv/

简单来说，uv是一个Rust写的Python环境与包管理器，旨在取代pip。

基本的uv安装配置

No! 我们的宝贵时间，不应该浪费在这种重复工作上！请直接参考官网教程。

对喜欢自己动手，不喜欢官方安装脚本的人来说，安装也很简单：直接去Github Release下载发行包，把uv和uvx丢进~/.local/bin，确保这个目录在PATH里，然后往~/.bashrc加两句：

1
2

eval "$(uv generate-shell-completion bash)"
eval "$(uvx --generate-shell-completion bash)"

开始使用

定义项目依赖

uv当然可以像pip那样使用，例如uv pip install numpy。但这似乎不是最优雅的方法。

对于uv来说，每个文件夹就可以被认为是一个Project。因此，推荐的做法是，在pyproject.toml定义项目依赖的pip包，以及版本号要求等。例如:

[project]
name = "my-project"
version = "0.0.1"
dependencies = [
  "numpy",
  "torch==2.5.1",
  "torchvision==0.20.1",
]

这之后，只需要执行一句:

uv sync

uv就会在当前目录.venv下创建一个虚拟环境，并安装pyproject.toml中定义的依赖项。

只需要等待处理完毕，然后source .venv/bin/activate，即可激活使用环境。

配置pypi软件源

众所周知，配置软件仓库镜像站已成为配环境的必备之路。

配环境笑传之Configure仓必。

uv默认不读取pip.conf中的配置项，因此先前针对pip配置的软件源不会影响uv的设置。

如果希望镜像配置仅对当前项目生效，可以直接编辑pyproject.toml，填入以下内容:

1
2
3

[[tool.uv.index]]
url = "https://mirrors.sustech.edu.cn/pypi/web/simple"
default = true

📌 重要

关于Pytorch

鉴于眼下PyTorch包没有更新频繁、好用高速的镜像站，基本还是走的官方下载渠道。

因此，如果只是简单需要在环境中安装指定CUDA/ROCM版本的PyTorch，不必像我下面的示例一样配置。

只需要简单地在uv pip install命令中指定--torch-backend参数即可。具体可参考文档。

例如：uv pip install "torch==2.8.0" --torch-backend=cu126，即可安装CUDA 12.6版本的Torch 2.8啦。

而对于一些使用独立软件源的包（如PyTorch），则需要定义额外的index项目，并在sources中显式要求这些包使用这些软件源:

[tool.uv.sources]
torch = [
  { index = "pytorch-cu121" },
]
torchvision = [
  { index = "pytorch-cu121" },
]
torchaudio = [
  { index = "pytorch-cu121" },
]

[[tool.uv.index]]
name = "pytorch-cu121"
url = "https://download.pytorch.org/whl/cu121"
explicit = true

上述index定义适用于提供index-url，也就是符合PEP 503规范的软件源。

而对于find-links的软件源，只需要在定义index时加一句format = "flat"即可。例如:

pyg_lib = [
  { index = "pyg-torch251-cu121" },
]
torch_scatter = [
  { index = "pyg-torch251-cu121" },
]

[[tool.uv.index]]
name = "pyg-torch251-cu121"
url = "https://data.pyg.org/whl/torch-2.5.1+cu121.html"
format = "flat"
explicit = true

怎么判断需要用的软件源要不要加format = "flat"一句呢？

很简单，看这个软件源提供的pip安装示例代码。如果其通过-i/--index-url <url>指定软件源，那就不需要加。反之，如果是通过-f/--find-links <url>指定的，那就需要。

📝 备注

TOML语法

包括我在内，一定有人好奇，为啥上面的配置文件中，为啥[[tool.uv.index]]中需要两对方括号[[]]？

这是TOML中的Array of Tables语法，Table实际上就是字典。

具体到uv配置文件，可以认为uv的配置项目中存在一个index数组，该数组包含了多条index信息字典。

例如：

[[tool.uv.index]]
url = "https://mirrors.sustech.edu.cn/pypi/web/simple"
default = true

[[tool.uv.index]]
name = "pytorch-cu121"
url = "https://download.pytorch.org/whl/cu121"
explicit = true

等价到JSON中就是:

{
    "tool": {
        "uv": {
            "index": [
                {
                    "url": "https://mirrors.sustech.edu.cn/pypi/web/simple",
                    "default": true,
                },
                {
                    "name": "pytorch-cu121",
                    "url": "https://download.pytorch.org/whl/cu121",
                    "explicit": true,
                },
            ],
        },
    },
}

配置文件细节

uv会从多个位置探测并加载可能的配置文件，按照大致的覆盖顺序为（后面的会覆盖先前的）：

System-Level Config
- Unix: /etc/uv/uv.toml和$XDG_CONFIG_DIRS/uv/uv.toml
- Windows: %SYSTEMDRIVE%\ProgramData\uv\uv.toml
Use-Level Config
- Unix: ~/.config/uv/uv.toml和$XDG_CONFIG_HOME/uv/uv.toml
- Windows: %APPDATA%\uv\uv.toml
Project-Level Config
- ./pyproject.toml
- ./uv.toml

和pyproject.toml不同，uv.toml中的配置项不需要包含tool.uv前缀。

例如，为了配置uv使用的pypi镜像站，在pyproject.toml中可以指定:

1
2
3

[[tool.uv.index]]
url = "https://mirrors.sustech.edu.cn/pypi/web/simple"
default = true

而在uv.toml中，则需要写成:

1
2
3

[[index]]
url = "https://mirrors.sustech.edu.cn/pypi/web/simple"
default = true

管理Python版本

uv还提供了管理Python版本的功能，可以像conda那样，安装指定版本的Python解释器。

例如，如果需要安装3.14版本的Python:

`1`	`uv python install 3.14`

同时，如果希望为每个项目指定版本号，也可以在pyproject.toml中指定requires-python。例如：

1
2

[project]
requires-python = ">=3.12,<3.13"

然而，uv使用的Python二进制包来自astral-sh/python-build-standalone项目，该项目是托管在Github上的，下载有时候并不顺畅。

一种解决思路是，在uv配置中指定python-install-mirror，指向你能访问到的最快的Github。例如，在pyproject.toml中:

1
2

[tool.uv]
python-install-mirror = "https://github.com/astral-sh/python-build-standalone/releases/download"

手动创建虚拟环境

是的，总有人喜欢掌控一切的感觉。

例如，如果就是不喜欢uv默认在每个项目下创建.venv的行为，就是喜欢创建一些集中式的虚拟环境，然后在其他项目中激活使用，那该怎么办呢？

很简单:

`1`	`uv venv /path/to/venv`

甚至还能指定一下Python版本号:

`1`	`uv venv ./venv -p 3.14`

不过，在可能的时候，uv会使用文件链接创建环境，多个环境内的相同依赖项会被复用。所以其实不太需要担心创建环境带来的磁盘重复开销问题。

但是，如果需要使用uv sync安装软件包，uv sync默认使用的环境是当前目录下的.venv。如何让uv sync使用任意虚拟环境呢？

也很简单，只需要先激活对应的环境，然后在uv sync加上一个参数--active即可，这个参数会命令uv使用和修改当前已经激活好的环境。

1
2

source /path/to/venv/bin/activate
uv sync --active

和Conda/Mamba一起使用

到目前为止，既然uv已经能实现管理Python版本的功能，实话说已经想不太出Conda/Mamba的用武之地。

如果希望在Conda中创建环境，然后使用uv管理软件包，那其实整体上和上面的手动创建虚拟环境是类似的。

不过，uv sync可能会遇到问题，无法识别Conda创建的环境。这时候就需要使用uv pip install安装包。

1
2

mamba activate -n myvenv
uv pip install -r pyproject.toml

uv pip install是最通用的包安装方法，-r pyproject.toml表示从pyproject.toml中读取依赖项并安装，该参数也可以是requirements.txt。

链接模式

在安装软件包时，如果目标虚拟环境和uv的缓存不在一个文件系统下，可能会弹出以下警告:

1
2
3

warning: Failed to hardlink files; falling back to full copy. This may lead to degraded performance.
If the cache and target directories are on different filesystems, hardlinking may not be supported.
If this is intentional, set `export UV_LINK_MODE=copy` or use `--link-mode=copy` to suppress this warning.

在Windows和Linux下，uv默认通过创建缓存到site-packages的hardlink以安装软件包。(MacOS下是创建的CoW克隆，不过我没有Mac，不太清楚实现细节)

然而，众所周知，Hardlink不能跨文件系统创建，那难道就要像上面的说明一样，给环境文件都做个全量复制？

好奇宝宝们，就不好奇一下，有没有比较折中的方案——SymbolLink吗？

有的，兄弟，有的。不过要翻一翻手册才能明确。只需要在命令行中指定--link-mode symlink:

`1`	`uv sync --link-mode symlink`

🚨 注意
Symlink模式与缓存兼容性
好奇宝宝们，有没有想过，在文件系统中，Symlink无法追踪一个源文件正在被多少个链接追踪。

也就是说，对于缓存系统内的某一个包，uv无法追踪缓存中的包被链接到了多少个虚拟环境中，这些虚拟环境是否还存在。

要命的是，uv cache clean的机制似乎是简单地删除整个缓存目录，删起来就不知道天地为何物了。

对Hardlink来说，这不会造成什么影响，因为文件系统会自动维护每个文件inode的指针数量。

但对Symlink来说，删除缓存后所有虚拟环境中的Symlink都会变成无根之树，全都指向不存在的路径。截至2025年7月，这一问题仍然存在。

考虑到这一问题主要出在无法创建硬链接的跨文件系统场景下，一种折中的方法是：在与uv缓存相同的文件系统上创建虚拟环境，然后将整个虚拟环境文件夹软链接到希望使用的地方，如项目路径下等。
1
2
3
ls /local/disk/.cache/uv/
uv venv /local/disk/envs/myenv
ln -s /local/disk/envs/myenv /another/fs/myproject/.venv

利用BTRFS快照实现快速Linux环境切换

Sun, 26 Jan 2025 16:00:00 +0800

对于喜欢折腾的人来说，经常会遇到环境玩崩的情况，在Linux下更是一件常事。而如果每次都要重装系统，其实又非常不方便，也没必要。

在BTRFS文件系统逐步稳定并可用的今天，如果我们将根文件系统迁移到了BTRFS，或许，我们可以借助BTRFS快照功能，实现Linux环境的无痛切换与还原？

思路

为了方便，我们假设一个非常无聊的例子：

希望在一个分区内，安装一个Debian系统
在Debian系统上，分别安装配置GNOME和KDE两个桌面环境
实现两个桌面环境的根文件系统互不干扰，可按需分别启动

需要说明的是，这套配置里，我们假设包括/usr, /etc等路径均没有分配独立的挂载点，否则那就太麻烦啦！/home是否独立挂载取决于环境隔离的程度。

仔细一想，想要实现上述功能的思路是非常简单的：

在BTRFS文件系统上安装一个基础操作系统
对基础操作系统进行快照
根据基础快照，创建两组新的读写快照（子卷），在两个子卷内分别安装GNOME和KDE环境，并按需切换

其实，以Debian为例，如果在安装系统时指定了根文件系统为BTRFS文件系统，Debian安装程序会贴心地为我们创建一个@rootfs子卷，而后每次启动电脑时，实际上都是将@rootfs子卷挂载成/节点。因此，以上步骤的前两步都已被自动完成。

似乎，我们只要解决第三步就行？但麻烦的也在这第三步。

GRUB的麻烦

回忆一下，Linux是如何确定自动挂载文件系统配置的？第一个想到的一定是/etc/fstab文件。

还是以Debian的为例，默认情况下，如果设置根文件系统为BTRFS，在/etc/fstab文件里面，我们可以找到类似于以下定义：

1
2

# / was on /dev/sda1 during installation
UUID=12345678-1234-1234-5678-123456789012 /               btrfs   defaults,subvol=@rootfs 0       0

显然，这一句的意思是，将硬盘上的@rootfs子卷，挂载到/路径上。

那么接下来，我们似乎只要创建一个@rootfs的快照子卷，然后修改上面的fstab文件，把subvol=后面替换成新子卷名称，就可以实现快速切换了？

一开始我也是这么认为的，直到我安装完KDE桌面重启后，对着仍然黑麻麻的屏幕两眼发黑，我才意识到不对劲。

让我们瞄一眼/boot/grub/grub.cfg文件：

menuentry 'Debian GNU/Linux' --class debian --class gnu-linux --class gnu --class os $menuentry_id_option 'gnulinux-simple-12345678-1234-1234-5678-123456789012' {
        # ......
        insmod btrfs
        # ......
        echo    'Loading Linux 6.1.0-30-amd64 ...'
        linux   /@rootfs/boot/vmlinuz-6.1.0-30-amd64 root=UUID=12345678-1234-1234-5678-123456789012 ro rootflags=subvol=@rootfs  quiet
        echo    'Loading initial ramdisk ...'
        initrd  /@rootfs/boot/initrd.img-6.1.0-30-amd64
}

好吧……事实上根文件系统的子卷名称，是写入到了GRUB配置文件里的。在GRUB引导时，会按照/boot/grub/grub.cfg的配置查找子卷，然后加载该子卷中的系统。

而要修改GRUB配置，似乎就有点麻烦了。如果手动修改配置，需要在每次安装完驱动或更新内核后再手动调整一遍配置，极其麻烦且容易疏漏。而如果希望自动修改，又暂时没有好主意。

重命名子卷

修改GRUB配置的路子走不通，系统默认引导@rootfs子卷的行为有点难修改。既然如此，为什么我们不通过替换@rootfs子卷的方式，狸猫换太子呢！

安装基本系统

首先正常安装Debian基本系统，在配置分区的时候，为/挂载点分配一个BTRFS文件系统。

进行基础配置

安装完系统后，重启进入基本系统，进行必要的配置，安装一些在不同环境下都用得上的包。也就是准备一个基本系统的过程啦！

拍摄基础快照

重启进LiveCD，挂载BTRFS分区整个卷：

1
2

mount /dev/sda1 /mnt
cd /mnt

我们给系统子卷@rootfs创建一个快照@sysbase（名字可以随意起），用于记录此刻基本系统的状态：

`1`	`btrfs subvolume snapshot @rootfs @sysbase`

如果希望基本系统内容不变，可以增加一个选项-r，以创建一个只读快照。

配置环境1

接着，重启电脑，按需要配置第一个环境，例如安装GNOME桌面等。

配置环境2

之后，如果我们想要从基本系统开始重新配置一个新环境，我们需要再次进入LiveCD，挂载BTRFS分区完整卷到/mnt下。

这回，我们需要把环境1，也就是现在的@rootfs先移到一边，也就是重命名一下。

`1`	`mv @rootfs @gnome-env`

现在，我们的硬盘上似乎只有两个子卷了：

1
2
3

/mnt/
├── @gnome-env
└── @sysbase

我们现在想让系统回到基本系统，也就是回到@sysbase的状态。怎么做呢？我们可以，给@sysbase再创建一个快照，让这个快照成为新的@rootfs：

`1`	`btrfs subvolume snapshot @sysbase @rootfs`

接着重启电脑，我们就回到了基本系统状态，此时我们对系统的修改，就变成了我们的环境2。

还要更多环境！

如果还需要更多环境，只需要像配置环境2时一样，将当前@rootfs重命名一下，再从基本系统，或者任何一个其他快照，创建一个新的@rootfs快照，重启电脑，就可以创建新环境了。

而如果我们希望在环境之间切换，也非常简单，同样地，将当前@rootfs重命名为其他名字，再将想要切换的快照重命名成@rootfs，或者创建一个新@rootfs快照都行。

如果我们玩坏了环境，也不用完全重装系统，只需要将不想要的环境子卷删除，btrfs subvolume delete @broken-env，再选择一个好的环境为@rootfs即可。非常灵活！

在Incus容器中使用NVIDIA显卡

Wed, 15 Jan 2025 22:00:00 +0800

📝 喜报

这张P104显卡，在搬运过程中由于震动，金手指不幸接触不良，享练习时长一年半。

目前，该显卡的任务已由另一张锻炼过的P102-100所替代。

在内存全面涨价，V100价格先落后涨的2026年，P104价格已经落到80出头，而P102也只需要180元。

很难说这些电子垃圾还有没有必要购买，但下一代A100等产品的大船恐怕没那么容易靠岸。

从某海鲜市场捡回一个P104显卡。

是的，2025年了，还在捡垃圾卡，毕竟在当前的大模型浪潮下，连退役多年的麦克斯韦架构Tesla M40 24G二手推理卡，都能从2年多前500上下的价格炒到现在的1200以上。就这，还不是每个商家都有货呢。

与此同时，曾经的垃圾佬挚爱P106-100，价格也来到了130以上的区间。有没有搞错，一两年前这玩意只需要大约一半的价钱。而P102-100价格已经来到了280附近，好吧，1080Ti的核心屏蔽一下，12G显存还是有一定可玩性的。

相较之下，捡来的这张P104-100，8G显存比P106的6G显然更有可玩性。而大约是1070水平的核心显然不能和P102比，但在我下单时只需要100出头的价格，不仅比P102便宜了一半有余，甚至还没有溢价后的P106昂贵。反正买回来是插在Linux主机上，不指望打游戏，P104似乎是省钱和好玩的平衡点。

显卡上机，暂时没有爆炸，这里记录一下如何把显卡映射到Incus容器环境里，让容器能利用显卡的方法。

不得不说，有时候捡垃圾确实能学到一些东西。或者说，捡垃圾的优点就在于，它能教会大家解决买全新产品不会遇到的问题的能力。

宿主机配置

NVIDIA驱动

显然，开源的驱动nouveau是不能用的。

常见的建议是安装英伟达官方打的.run驱动包，这当然可以，但我个人不是很喜欢这种方法。

事实上，只需要装上系统apt源里的英伟达闭源驱动，如Debian的nvidia-driver包，或者是Ubuntu的nvidia-headless-550之类，就是OK的了。

除了驱动，还要在主机上安装一个NVIDIA Container Toolkit，这个工具能自动将主机上的NVIDIA运行时及工具等挂载到容器中。

一定会有人问：要不要在主机上装CUDA Toolkit？

在Ubuntu官方提供的教程中，的确提到需要在宿主机上安装CUDA Toolkit。但根据我的实验，如果在宿主机上没有使用CUDA工具如nvcc等的需要，其实完全没必要在宿主机上装CUDA Toolkit。

实际上，根据网上的说法，CUDA Toolkit主要包含三部分内容：

NVIDIA驱动程序（跟我们用apt装的，.run文件装的没啥区别）
CUDA SDK（NVCC，编译器，库文件，示例程序等）
其他工具（Debugger等）

显然，后两个部分实际上，要么是静态文件，要么是运行在用户态的程序，这些程序显然遵循“在哪里使用，就在哪里安装”的方法比较好。

因此，关于CUDA的结论是：

如果完全不涉及到C++ CUDA工具的编译等任务，可以完全不安装CUDA Toolkit；
如果只是想在容器中使用nvidia-smi等工具，也不需要安装CUDA Toolkit，系统会自动将宿主机的nvidia-smi映射到容器中；
如果需要在容器里使用NVCC等SDK工具，则需要在容器中安装CUDA Toolkit；

📝 备注

P104等矿卡与驱动问题

显然，P104这样的矿卡流入用户市场，并不是皮衣男想看到的。

一般来说在Windows上使用矿卡，都建议使用民间的魔改驱动。但在Linux下就比较微妙了。

官方驱动是否会限制显卡频率？

有坊间传闻说，自从535版本开始，N卡就在驱动程序层面限制了矿卡的功耗。

但就我测试的情况来看，使用Debian软件源中提供的535.216版本N卡驱动，P104在nvidia-smi工具中仍然能跑到180W的功率。

因此暂时无法确认该说法是否正确，以及该说法的适用范围。

矿卡能否使用NVENC视频解码器

另一个坊间传闻是，皮衣男还限制了矿卡上的NVENC视频编码器，要使用民间魔改驱动才能解锁NVENC。

我测试的结果是，使用ffmpeg命令无法显示出当前系统支持NVENC编码器。而在jellyfin-ffmpeg中设置使用NVENC硬件加速会报错。

因此暂时没有找到使用矿卡NVENC编码器的有效方法。

容器配置

时至今日，虚拟化GPU并将物理GPU与虚拟机共享，已经不是一件新鲜事了，从WSL到Docker，都有非常成熟且广泛的应用。

在Incus/LXD容器框架下，这一功能同样也是被支持的。然而，Incus的文档实在是语焉不详，缺少明确可复用的示例。说人话就是，官方文档看了一头雾水，没东西可以抄，最后绝知此事还是得躬行。

首先初始化一个容器：

`1`	`incus create images:debian/12 gpu-test`

指定使用显卡：

1
2

incus config set gpu-test nvidia.runtime=true nvidia.driver.capabilities=all
incus config device add gpu-test nvidia-0 gpu

到现在，启动容器，在/dev/下就可以找到N卡的设备文件了，同时也可以使用nvidia-smi等工具查看显卡信息。

值得一提的是，上面指定的NVIDIA Driver Capability，可选的值及意义如下表：

Driver Capability	Description
compute	required for CUDA and OpenCL applications.
compat32	required for running 32-bit applications.
graphics	required for running OpenGL and Vulkan applications.
utility	required for using nvidia-smi and NVML.
video	required for using the Video Codec SDK.
display	required for leveraging X11 display.

一般来说，如果只需要运行CUDA计算等，指定为utility,compute就足够了。

附赠：Micromamba配置教程

🚨 注意

悲报

就在这篇笔记写成之后没几天，PyTorch宣布自v2.6开始不再发布官方Conda包。如有需要，请直接安装 pip 包或者安装 conda-forge 渠道包。

好吧，除非有同时使用多个版本Python的需求，不然conda/mamba在Python生态中的应用场景就比较狭窄了。

mamba is a CLI tool to manage conda s environments.

If you already know conda, great, you already know mamba!

Mamba是一个C++编写的Conda实现，而Micromamba是Mamba的精简版，不附带base环境，只需要一个独立的可执行文件就能承担起以往Conda的职能，而且速度更快。

安装很简单，只需要前往Micromamba的Github Release下载最新的包，解压后提取其中的bin/micromamba可执行文件，放到自己的可执行文件目录下，例如~/.local/bin，然后确保将这一目录加入到PATH环境变量中，就算安装好了一半。

接着执行：

`1`	`micromamba shell init -s bash -r ~/micromamba`

这会修改~/.bashrc，配置与Micromamba相关的环境变量。如果使用的是zsh，则需要将上面的shell部分改成-s zsh。

接下来我们还要配置使用的软件源。事实上，Micromamba与以往的Conda的配置文件.condarc完全兼容，如果曾经安装过Conda，其实不需要重复配置。

如果是全新安装，则可以编辑~/.mambarc，填写以下内容：

channels:
  - defaults
show_channel_urls: true
default_channels:
  - https://mirrors.sustech.edu.cn/anaconda/pkgs/main
  - https://mirrors.sustech.edu.cn/anaconda/pkgs/free
  - https://mirrors.sustech.edu.cn/anaconda/pkgs/r
  - https://mirrors.sustech.edu.cn/anaconda/pkgs/pro
  - https://mirrors.sustech.edu.cn/anaconda/pkgs/msys2
custom_channels:
  conda-forge: https://mirrors.sustech.edu.cn/anaconda/cloud
  msys2: https://mirrors.sustech.edu.cn/anaconda/cloud
  bioconda: https://mirrors.sustech.edu.cn/anaconda/cloud
  menpo: https://mirrors.sustech.edu.cn/anaconda/cloud
  pytorch: https://mirrors.sustech.edu.cn/anaconda/cloud
  simpleitk: https://mirrors.sustech.edu.cn/anaconda/cloud

现在似乎就可以用Micromamba创建环境并安装包了。

报错

报错1: Critical libmamba: No CA certificates found on system, aborting

`1`	`sudo apt install ca-certificates`

报错2: Error libmamba: ZSTD decompression error: Unknown frame descriptor

尝试换一个镜像源。

在VSCode中使用Jupytext实现ipynb与py文件转换

Wed, 08 Jan 2025 16:00:00 +0800

对于经常需要使用Python进行数据分析与处理的人来说，Jupyter Notebook是一个非常不错的选择。但Notebook文件在版本管理中，常常会造成麻烦。

这是因为，Notebook的.ipynb文件格式上实质是一个Json文件，包含了相当多的辅助信息，记录了诸如单元格类型、执行次数、单元格输出等信息，且源代码实质上已经被转义成Json兼容的字符串数组。

这一特性导致，在使用Git之类版本管理工具管理Notebook源代码时，其实并不方便。举例来说，即便是切换了Notebook运行的Kernel，也会修改Notebook文件，在版本管理工具中就是一次文件改动。

显然，大多数情况下，我们希望追踪的是Notebook中的源代码，单元格输出等信息并不是使用Git等工具管理代码仓库的目标。

因此，我们是否能找到一种方法缓解上述问题呢？

用Python文件存储不就好了？

是的！非常正常的想法，既然在Notebook中我们编写的都是.py代码，那么为什么我们不能将Notebook直接存储为.py文件呢？

事实上，无论是Jupyter的浏览器客户端，还是nbconvert模块，抑或是VSCode之类的编辑器，都提供了将Notebook转换为Python源代码文件的功能。

并且，只需要辅助以正确的助记符，包括Markdown单元格等信息，都可以被正常存储。

怎么转换回Jupyter Notebook？

存储的问题解决了，但怎么从.py文件转回.ipynb文件呢？

这时候就需要一个名为jupytext的模块了。详情请看：https://jupytext.readthedocs.io/en/latest/。

手动转换好麻烦

不过，设想一下，如果用手动的方法，我们每次编辑一个文件将包含以下几个流程：

将.py转换成.ipynb
在.ipynb文件上编程和调试
一切OK后，将.ipynb转换为.py
在Git中提交更改

很麻烦对吧？有没有能帮我们自动做这些的程序呢？

当然有！jupytext本身就提供了将.ipynb与.py配对的能力。

具体来说，只要将一个.ipynb文件与指定的格式进行配对，配对完成后，当修改两个文件的其中一个，同步一下，另一个文件也将自动反映出最新更改。

这样一来，只需要在Git仓库里追踪.py文件，然后尽情修改.ipynb，所有更改都会自动同步。我们就实现了，在.ipynb文件中调试，用.py文件存储的目标。

而所谓的配对，其实也没什么特别的，无非就是在配对文件.ipynb的metadata里，写入配对的格式信息，例如一个最简单的HelloWorld Notebook在配对后，大概是这样的：

{
    "cells": [
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {},
            "outputs": [],
            "source": [
                "print(\"Hello World!\")"
            ]
        }
    ],
    "metadata": {
        "jupytext": {
            "formats": "ipynb,py:percent"
        },
        "kernelspec": {
            "display_name": "myvenv",
            "language": "python",
            "name": "python3"
        },
        "language_info": {
            "name": "python",
            "version": "3.12.7"
        }
    },
    "nbformat": 4,
    "nbformat_minor": 2
}

详情参见上述jupytext文档中的示例。

VSCode里怎么办呢

然而，jupytext的配对功能仅限于网页客户端的原生Jupyter，VSCode似乎并没有对这一功能的支持，因此似乎只能每次手动敲命令进行转换。

等一等，敲命令？那能不能让VSCode自动为我们执行转换的命令呢？别忘了VSCode的任务系统！

具体来说，我们需要做以下工作：

使用命令实现配对

由于配对是需要显式执行的，因此我们首先用命令实现这一点：

jupytext --set-formats ipynb,py:percent test-hello.ipynb

# Wildcard is OK for multiple files
jupytext --set-formats ipynb,py:percent *.ipynb

注意到上述命令中的ipynb,py:percent了吗？它的意思是将一个.ipynb文件与 percent 格式的.py文件配对起来。

什么是 percent 格式呢？实际上就是通过# %%等助记符作为Notebook单元格的划分，方便阅读也方便将.py转换回.ipynb文件。这一格式的介绍也请阅读jupytext的文档啦。

利用VSCode Tasks实现一键同步

现在，我们可以试着借助VSCode Tasks，实现.py与.ipynb文件内容更改的一键同步。

编辑工作路径.vscode/tasks.json文件（没有就新建一个），编辑内容如下：

{
    // See https://go.microsoft.com/fwlink/?LinkId=733558
    // for the documentation about the tasks.json format
    "version": "2.0.0",
    "tasks": [
        {
            "label": "JupyText Sync",
            "type": "shell",
            "command": "${command:python.interpreterPath}",
            "args": [
                "-m",
                "jupytext",
                "--sync",
                "${file}"
            ],
            "group": {
                "kind": "build",
                "isDefault": true
            }
        }
    ]
}

保存文件。

现在，每当我们在编辑.ipynb或.py文件的其中一个并保存后，只要我们按下Ctrl + Shift + B键，运行VSCode的构建任务，我们配对的同名文件就会自动同步更改。

Incus网络配置指北

Wed, 04 Dec 2024 22:00:00 +0800

网络配置大概是容器配置中最无聊的部分了。

Incus与Macvtap

什么是Macvtap？太简单了请自行百度。总之就是快速将虚拟机/容器作为一个独立机器，暴露给主机所在的网络的功能。

需要注意，Macvtap能实现与局域网内其他主机的通信，但唯独不能实现与主机的通信！

如果有和主机通信的需要，建议为虚拟机配置一块额外的网卡，或使用传统的Bridge网络。

# 创建一个配置文件
# macvlan-enp4s0是配置文件名称
# eth0是虚拟机中这个macvtap网卡的名称
# enp4s0是想要连接到的主机网卡名称
incus profile device add macvlan-enp4s0 eth0 nic nictype=macvlan parent=enp4s0

# 以该配置创建一个新容器
incus init images:debian/12 my-debian --profile default --profile macvlan-enp4s0

# 或是为虚拟机设置配置文件
incus profile add my-debian macvtap-enp4s0

Incus端口发布

在Docker中，我们可能已经习惯了采用-p 10086:80这样的命令，将容器的一个端口映射到主机上另一个端口。

这一目标在Incus中，需要借助Proxy这一设备类型实现，不过会稍显复杂。

📝 备注

Network Forward转发与Proxy有什么区别？
参考：Difference between network forward and proxy device

The proxy device is instance specific and can forward connections in either direction, between protocols, and when operating in non Nat mode doesn’t require a network connection between host and instance.

A forward on the other hand is more like a proxy device operating in Nat mode. But its defined at the network level rather than instance level and allows sharing an ip between multiple instances because it can forward different ports to different ips.

首先，如果是绑定到普通用户默认Project的容器实例，我们要先解除该Project禁止设置Proxy设备的限制。

`1`	`sudo incus project edit user-1000`

是的，sudo，除非账户在incus-admin用户组里，否则请用sudo。

在config下添加一行：

1
2
3

config:
  # ......
  restricted.devices.proxy: allow

保存。现在我们就可以向容器示例添加proxy设备了。

假设在容器my-http里，有一个Nginx正在监听80端口，我们现在希望将容器的80端口映射到主机的10086端口，以实现访问主机的10086端口，就能访问到容器的80端口。那么，命令如下：

`1`	`incus config device add my-http port10086to80 proxy connect="tcp:127.0.0.1:80" listen="tcp:0.0.0.0:10086"`

完成以后，可以在主机运行curl http://127.0.0.1:10086命令，查看绑定是否成功。

如果计划使用反向代理将外部的请求转发到容器，同时禁止外部网络直接通过访问端口号访问到容器内服务，那么可以将最后的listen字段中IP，改成127.0.0.1。

💾几分钟能了解BTRFS吗？💾

Thu, 28 Nov 2024 16:00:00 +0800

安装相关组件

`1`	`sudo apt install btrfs-progs`

创建普通文件系统

`1`	`sudo mkfs.btrfs -L MyDisk /dev/sdxy`

创建RAID文件系统

`1`	`sudo mkfs.btrfs -f -d raid1 -m raid1 /dev/sdc1 /dev/sdd2`

-f: 强制执行，即无视指定分区上现存的文件系统。
-d raid1: 指定数据块存储模式。具体请参考官方手册RAID功能介绍。
-m raid1: 指定Metadata块存储模式。具体请参考官方手册RAID功能介绍。

在后面指定跨盘卷使用到的块设备即可。

设置卷名

`1`	`sudo btrfs filesystem label /dev/sdc1 MyData`

子卷(Subvolume)

创建子卷：

1
2

# 假设主卷已经挂载到/mnt/mydata
sudo btrfs subvolume create /mnt/mydata/@mysubvol

命令行挂载子卷：

`1`	`sudo mount -o subvol=@mysubvol UUID=abcd1234-5678-90ab-cdef-1234567890ab /some/place/`

访问子卷内容：

# 可以挂载后访问：
sudo mount -o subvol=... UUID=... /some/place/
cd /some/place/

# 当然还可以直接从卷根挂载点访问
cd /mnt/mydata/@mysubvol

快速问答

Q: 子卷是啥？

A: 就理解成BTRFS文件系统下，一个可以独立挂载，独立快照，独立操作的子文件夹吧。（尽管内部实现显然不是这样）

Q: 为啥子卷名称前面有个@符号？

A: 似乎是约定俗成，换成其他符号也行，不用也行。参阅Re: btrfs subvolume naming scheme.

Q: fstab中如何使用子卷？

A: 看下文。

挂载(fstab)

BTRFS文件系统的挂载和其他文件系统别无二致。

在使用块设备挂载RAID卷时，只需要指定其中一个块设备，就可以完成挂载。

不过，在/etc/fstab中设置挂载点，尤其是跨盘卷时，建议使用UUID进行挂载。

查看UUID:

# Recommended
sudo btrfs filesystem show

# OR
sudo blkid

# OR
ls -lha /dev/disk/by-uuid/

注意我们需要的是整个BTRFS卷的UUID，在RAID中不是某个单一块设备的PARTUUID。

接着编辑/etc/fstab:

最简单的：

`1`	`UUID=abcd1234-5678-90ab-cdef-1234567890ab /mnt/mydata btrfs defaults 0 0`

RAID也是一样：

`1`	`UUID=abcd1234-5678-90ab-cdef-1234567890ab /mnt/mydata btrfs defaults 0 0`

挂载子卷（注意这里使用的UUID仍然是主卷的UUID，不要与PARTUUID混淆）：

`1`	`UUID=abcd1234-5678-90ab-cdef-1234567890ab /media/mysubvol/ btrfs defaults,subvol=@mysubvol 0 0`

我喜欢的外挂硬盘挂载选项，可以在硬盘缺失时自动跳过检查：

`1`	`UUID=abcd1234-5678-90ab-cdef-1234567890ab /media/mysubvol/ btrfs defaults,subvol=@mysubvol,nofail,x-systemd.automount,x-systemd.device-timeout=3 0 0`

查看磁盘空间占用

需要注意，系统的du命令输出中，BTRFS的空间统计信息并不总是准确的。

`1`	`sudo btrfs filesystem df /mnt/mydata`

全盘检错

BTRFS的一大特色就是自动化的错误检测。

在BTRFS的Checksum Tree里，保存着整个文件系统中包括Metadata块与数据块的Checksum，而在每次读取这些数据时，BTRFS会自动进行校验，进而发现硬盘数据存在的错误。

不过，有时我们还希望主动执行检查，校验硬盘上的数据是否发生了损坏。那么我们可以这么做：

`1`	`sudo btrfs scrub start /mnt/mydata`

上面一条命令将会启动一个后台检查任务，检查整个文件系统存在的错误。对于RAID系统，检查会在多块磁盘上并行进行。

如果发现了数据错误且配置了RAID等数据冗余，BTRFS将会自动尝试从好数据中恢复损坏的数据。如果只是想查错，不希望BTRFS自动纠错，可以用-r参数指定只读模式运行。

开始检查后，可以用以下命令读取检查进度与报告：

`1`	`sudo btrfs scrub status /mnt/mydata`

查询读写错误发生次数

`1`	`sudo btrfs device stats /mnt/mydata`

简易使用局域网Local域名

Wed, 14 Aug 2024 12:00:00 +0800

习惯了在公网服务器上用多个子域名访问不同应用，在局域网环境中我们也常常希望这么做。

对于自带DNS服务器并维护了.lan域名的路由器来说，一切非常简单，不需要额外配置就能直接使用主机名.lan解析其他主机地址。当然，也仅限于此，增加子域名解析或泛域名解析还需要额外配置。

在局域网里增设一个DNS服务器，直接解析内网主机的地址，或许这是最为强大的方法，但也或许是最麻烦的方法。

Windows的NetBIOS，以及Linux的Avahi，是操作系统附带的主机地址广播方案，在我看来似乎是更加灵活的选择。

且Windows 10自较为近期的版本开始，就自带解析 .local mDNS的组件，Windows和Linux之间的地址广播方案实现了互通。

接下来就以在Linux服务器上配置.local域名作为例子。

基本组件

在Debian系统上直接安装：

`1`	`sudo apt install avahi-daemon avahi-utils`

现在起，<主机名>.local将指向这台主机。

添加额外域名

在一些服务，尤其是HTTP服务中，通过不同域名指向不同服务是非常便利的方法，如blog.<主机名>.local指向博客，nextcloud.<主机名>.local指向Nextcloud实例等等。

甚至，有些HTTP应用必须运行在/下，无法通过绑定子目录方式访问，此时必须为其分配独立的域名/子域名。

Avahi的确可以添加泛域名或子域名记录，但大部分操作系统并不能正确解析mDNS的泛域名或子域名记录，或是依赖客户端系统的复杂配置，并不简单易行。

但是，在局域网环境中，域名空间常常充足，退而求其次，我们完全可以为同一台主机分配多个.local记录，只要不与网内其他主机冲突即可。

avahi-utils软件包提供了avahi-publish工具，该工具可以广播用户指定的mDNS记录到内网。例如：

`1`	`avahi-publish -a -R another.local 192.168.1.123`

这可以将another.local域名指向IP地址192.168.1.123。-R选项代表不要广播反向（IP到主机名）解析记录，由于IP地址到主机名的唯一性，这一选项应当被保留。

也可以将其编写成一个Systemd服务单元，例如，可以将以下内容填入/etc/systemd/system/avahi-alias@.service：

[Unit]
Description=Publish %I as alias for %H.local via mdns
Requires=avahi-daemon.service
After=avahi-daemon.service

[Service]
Type=simple
ExecStart=/bin/bash -c "/usr/bin/avahi-publish -a -R %I $(avahi-resolve -4 -n %H.local > /dev/null && ip route get 1 | awk '{print $7;exit}')"
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

之后执行：

1
2

sudo systemctl daemon-reload
sudo systemctl enable --now avahi-alias@another.local

即可对外发布mDNS记录。

使用Distrobuilder构建Incus容器镜像

Wed, 07 Aug 2024 21:00:00 +0800

在拥有了自己的Distrobuilder后（还没有？请参见：这篇博客），我们来一起构建用于Incus的容器镜像，实现容器镜像自由吧！

一定会有人疑惑：既然已经有了LXC镜像站，为什么还需要自己构建镜像呢？

这是因为，本文希望描述一个全程可控的，避免过度抽象细节的，创建Incus容器镜像的方法。

预先准备

需要在系统上安装distrobuilder，可以使用snap下载，也可以自己构建。

案例1: Alpine Linux镜像

准备根文件系统(rootfs)

既然我们在讨论可控的构建过程，那么这一定包括一个可控的根文件系统(Root FileSystem, rootfs)。

让我们打开downloads | Alpine Linux，下拉找到MINI ROOT FILESYSTEM项目，下载对应架构的根文件系统。

例如，对于64位系统来说，我们将需要下载alpine-minirootfs-3.20.2-x86_64.tar.gz文件。中间的版本号请不要介意。

能不能用镜像站完成这一下载呢？又或者能不能用自己打包的Alpine Linux根文件系统呢？当然可以！这正是可控过程的魅力所在。

当然，distrobuilder实际上也已将下载rootfs的过程封装在程序中。就Alpine Linux来说，distrobuilder下载的rootfs和我们现在手动下载的是同一个文件。

如果更希望让distrobuilder代劳，请跳过当前这一步骤，后面会再展开介绍。

准备构建配置模板

构建镜像时需要的许多信息都由模板文件提供，如镜像的名称、类型、发行版，还有需要安装的软件包、执行的动作等等。

在distrobuilder中，镜像的模板文件是一个YAML文件，标准格式在官方仓库doc/examples/scheme.yaml中给出，文末也附有该文件复制过来的内容：

只不过，格式文件里，有非常多对键值。看起来一头雾水对吧？没关系，加法做不通我们可以做减法。

转到lxc/lxc-ci/images，这一目录下的镜像配置文件，就是Incus官方镜像服务器上，镜像构建所采用的配置文件。我们目前正在构建Alpine Linux，所以我们直接复制alpine.yaml文件中的内容到本地。由于内容太长，同样地，原始内容放在文末。

这文件也太长了吧？而且仔细一看，还有很多似乎我们不太用得上的配置项，例如适用于虚拟机镜像的命令，在容器中是用不到的。因此，让我们来进一步修改这些配置。

修改构建配置文件

Image: 容器镜像配置

首先，文件的第一节image部分，主要定义了镜像的名称和版本号等信息。

为了避免与官方构建的Alpine Linux镜像名称冲突，我们可以稍微修改一下这部分内容：

image:
  distribution: "Custom Alpinelinux"
  name: custom-alpine
  release: 3.20

Source: 镜像rootfs来源配置

配置文件第二节，source部分，主要定义了用于构建容器镜像的rootfs如何获得。由于各Linux发行版的rootfs定义与下载地址都有差异，因此distrobuilder预定义了许多Source，用于解析各种操作系统的rootfs下载规则。

对于Alpine Linux，distrobuilder已经定义好了alpinelinux-http这一Source，因此如果希望distrobuilder帮我们自动下载rootfs，此处可定义如下：

source:
  downloader: alpinelinux-http
  same_as: 3.12
  url: https://mirrors.hust.edu.cn/alpine/

其中，URL可以是任意Alpine Linux镜像站，以上例子使用了华中科大镜像站。不过，URL也可以file://开头，指向本地已经下载好的rootfs文件包。

如你所见，示例配置文件包含了一大段GPG公钥，用于验证下载的rootfs。如果信任下载源与下载文件完整性，并希望删掉keys部分以缩简配置文件，请在source节内加上skip_verification: true选项。

不过，既然我们正在尽可能追求可控，我们一定会想：

alpinelinux-http源在下载rootfs文件之外，是否还有额外的操作/Tricks？
不考虑后文安装软件包等定制操作，在当前这一步是否有通用于所有Linux发行版rootfs的方法？
是否可以利用已预先准备好的rootfs？

尽管根据sources/alpine-http.go源代码，就目前来说，并没有什么下载之外的额外小Tricks。但到目前为止，distrobuilder最新版3.0并没有直接提供使用现有rootfs目录直接构建容器系统的选项。如果直接在配置文件中删除source一节，进行构建时也会报错。

但是，distrobuilder的确提供了一种使用任意rootfs文件包的Source，即rootfs-http，相关源代码可见sources/rootfs-http.go。简单来说只需要提供一个指向rootfs包的URL，本地网络皆可。

因此，上述source节也可以改为（使用file://指向本地文件时需要使用绝对路径）：

1
2
3

source:
  downloader: rootfs-http
  url: file:///absolute/path/to/alpine-minirootfs-3.20.2-x86_64.tar.gz

Target: 目标特定配置

如果仅希望构建Incus容器镜像，不需要LXC镜像和虚拟机镜像，可以直接把这一节大幅精简：

1
2

targets:
  incus:

如有需要，请直接参阅Targets - distrobuilder documentation官方文档。

Files: 文件生成规则配置

和上面类似地，如果不需要Incus虚拟机镜像，仅仅需要保留用于Incus容器的部分，可以直接删除掉所有包含以下标记的虚拟机专用文件生成规则。

1
2

types:
  - vm

Packages: 软件包安装预定义配置

这部分将定义Incus在构建镜像时，需要使用何种包管理器，安装哪些软件包，大部分内容可以直接照抄示例。同上，可以删掉所有虚拟机限定的配置。

重点讨论一下软件源相关配置。官方手册中，与定制软件源相关的选项位于packages节下，可以通过添加repositories节设置额外的软件源。例如：

packages:
  # Other parameters
  # ...
  repositories:
    - name: hust
      url: |-
        https://mirrors.hust.edu.cn/alpine/v3.20/main
        https://mirrors.hust.edu.cn/alpine/v3.20/community

但是，这种方法会将新软件源附加到原本的软件源后，并不会替换掉速度可能非常缓慢的官方软件源。

如果希望替换掉rootfs中的官方软件源，我们可以不采用这种方案，请往下看。

Actions: 自定义操作

在这一部分，我们可以定义在容器构建的不同的时机要执行的操作(Action)。

目前，distrobuilder提供的执行时机（触发器/Trigger）包括：

post-unpack: 在rootfs被解压释放后执行。
post-update: 如果packages.update为true，在包管理器完成更新后执行。
post-packages: 在包管理器安装完所有指定的包后执行。
post-files: 在files配置块执行完成后执行。这一部分默认仅在build-lxc, build-incus, pack-lxc和pack-incus操作中执行。如果希望在build-dir操作中也执行这一块，需要指定--with-post-files选项。

例如，如果我们希望把rootfs中官方的软件源配置为镜像站，则可以添加一个post-unpack操作，内容如下：

actions:
- trigger: post-unpack
  action: |-
    #!/bin/sh
    set -eux
    sed -i 's/dl-cdn.alpinelinux.org/mirrors.hust.edu.cn/g' /etc/apk/repositories

该命令会在rootfs解压挂载后，容器执行apk update更新软件源之前执行。

Mappings: 架构名称映射配置

这部分主要是告诉Distrobuilder如何处理不同架构名称之间的映射关系，如amd64与x86_64，aarch64与arm64等。

这部分按照模板直接保留就行，详情见Mappings - distrobuilder documentation官方文档。

不得不感慨一下，Linux由于各种历史包袱和不一致的规范，有时会略显混乱。

最终配置文件

image:
  name: custom-alpine
  distribution: "Custom Alpinelinux"
  release: 3.20

source:
  downloader: rootfs-http
  url: file:///absolute/path/to/alpine-minirootfs-3.20.2-x86_64.tar.gz

targets:
  incus:

files:
- path: /etc/hostname
  generator: hostname

- path: /etc/hosts
  generator: hosts

- path: /etc/network/interfaces
  generator: dump
  content: |-
    auto eth0
    iface eth0 inet dhcp
    hostname $(hostname)

- path: /etc/inittab
  generator: dump
  content: |-
    # /etc/inittab
    ::sysinit:/sbin/openrc sysinit
    ::sysinit:/sbin/openrc boot
    ::wait:/sbin/openrc default

    # Set up a couple of getty's
    ::respawn:/sbin/getty 38400 console
    tty1::respawn:/sbin/getty 38400 tty1
    tty2::respawn:/sbin/getty 38400 tty2
    tty3::respawn:/sbin/getty 38400 tty3
    tty4::respawn:/sbin/getty 38400 tty4

    # Stuff to do for the 3-finger salute
    ::ctrlaltdel:/sbin/reboot

    # Stuff to do before rebooting
    ::shutdown:/sbin/openrc shutdown

- path: /etc/inittab
  generator: template
  name: inittab
  content: |-
    # /etc/inittab
    ::sysinit:/sbin/openrc sysinit
    ::sysinit:/sbin/openrc boot
    ::wait:/sbin/openrc default

    # Set up a couple of getty's
    ::respawn:/sbin/getty 38400 console

    # Stuff to do for the 3-finger salute
    ::ctrlaltdel:/sbin/reboot

    # Stuff to do before rebooting
    ::shutdown:/sbin/openrc shutdown

- name: meta-data
  generator: cloud-init
  variants:
  - cloud

- name: network-config
  generator: cloud-init
  content: |-
    version: 1
    config:
    - type: physical
      name: eth0
      subnets:
      - type: dhcp
        control: auto
  variants:
  - cloud

- name: user-data
  generator: cloud-init
  variants:
  - cloud

- name: vendor-data
  generator: cloud-init
  variants:
  - cloud

packages:
  manager: apk
  update: true
  cleanup: true
  sets:
  - packages:
    - alpine-base
    - logrotate
    - doas
    action: install

  - packages:
    - cloud-init
    - openssh
    - e2fsprogs-extra
    action: install
    variants:
    - cloud

  - packages:
    - py3-pyserial
    - py3-netifaces
    action: install
    variants:
    - cloud
    releases:
    - 3.17
    - 3.18
    - 3.19
    - 3.20
    - edge

actions:
- trigger: post-unpack
  action: |-
    #!/bin/sh
    set -eux
    sed -i 's/dl-cdn.alpinelinux.org/mirrors.hust.edu.cn/g' /etc/apk/repositories

- trigger: post-packages
  action: |-
    #!/bin/sh
    set -eux

    rm -f /var/cache/apk/*

- trigger: post-packages
  action: |-
    #!/bin/sh
    set -eux

    # Rewrite configuration for LXC
    sed -i 's/#rc_sys=""/rc_sys="lxc"/' /etc/rc.conf

    # Honor fstab by not making the localmount script a noop
    sed -i 's/-lxc//' /etc/init.d/localmount

    # Enable services
    for svc_name in bootmisc syslog devfs; do
        ln -s /etc/init.d/${svc_name} /etc/runlevels/boot/${svc_name}
    done

    for svc_name in networking crond; do
        ln -s /etc/init.d/${svc_name} /etc/runlevels/default/${svc_name}
    done
  types:
  - container

- trigger: post-files
  action: |-
    #!/bin/sh
    set -eux

    setup-cloud-init
  variants:
  - cloud

mappings:
  architecture_map: alpinelinux

我们将最终的配置文件保存，随便起个名字，比方说alpine.yaml即可。

开始构建

新建rootfs和images两个文件夹，分别用于暂存解压的rootfs，以及构建生成的镜像文件。

1
2

mkdir rootfs
mkdir images

首先需要执行的是build-dir指令。

`1`	`sudo distrobuilder build-dir alpine.yaml rootfs`

再接着执行pack-incus指令。

`1`	`sudo distrobuilder pack-incus alpine.yaml rootfs images`

等待一切完成，images文件夹下就存放着构建好的容器镜像了。

此时一定有人会问：为什么要分两步？为什么不直接执行build-incus指令？

答案当然是可以的。

`1`	`sudo distrobuilder build-incus alpine.yaml images`

有什么区别呢？我们来看看Distrobuilder开发者在论坛中的讨论：

Oops, I said build instead of pack here as that’s likely what you actually want to use.build-incus is equivalent of build-dir + pack-incus.

The reason why we do it in two steps in our CI is because we produce both LXC and Incus images so that lets us use the same rootfs for both. But if all you care about is the LXD/Incus image, just use build-incus directly.

导入Incus并开始使用

拥有了镜像，只需要导入Incus就可以开始使用了。

`1`	`incus image import images/incus.tar.xz images/rootfs.squashfs --alias custom-alpine/3.20`

命令末尾的--alias选项用于给镜像定义一个别名。如果没有别名，我们就只能用镜像的哈希指代镜像了。

接着创建实例，启动镜像。

1
2

incus launch local:custom-alpine/3.20 test-alp
incus exec test-alp -- /bin/ash

附录

配置文件

doc/examples/scheme.yaml

# This example contains every possible key

image:
  description: |-
    here goes the image description
  distribution: distro
  release: release
  architecture: x86_64
  expiry: 30d
  variant: default
  name: distro-release-x86_64
  serial: some-random-string

source:
  downloader: ubuntu-http
  url: http://archive.ubuntu.com
  keys:
    - 0xdeadbeaf
  keyserver: http://keyserver.ubuntu.com
  variant: default
  suite: suite
  same_as: bionic
  skip_verification: false
  components:
    - main

targets:
  lxc:
    create_message: |-
      You just created an {{ image.description }} container.

      To enable SSH, run: apt install openssh-server
      No default root or user password are set by LXC.

    config:
      - type: all
        before: 5
        content: |-
          lxc.include = LXC_TEMPLATE_CONFIG/ubuntu.common.conf

      - type: user
        before: 5
        content: |-
          lxc.include = LXC_TEMPLATE_CONFIG/ubuntu.userns.conf

      - type: all
        after: 4
        content: |-
          lxc.include = LXC_TEMPLATE_CONFIG/common.conf

      - type: user
        after: 4
        content: |-
          lxc.include = LXC_TEMPLATE_CONFIG/userns.conf

      - type: all
        content: |-
          lxc.arch = {{ image.architecture_personality }}
  incus:
    vm:
      size: 2147483648
      filesystem: ext4

files:
  - generator: dump
    path: /some/path
    content: |-
      here goes the content
    name: name
    mode: 0644
    gid: 1000
    uid: 1000
    template:
      properties:
        key: value
      when:
        - always
    templated: true
    releases:
      - a
      - b
    architectures:
      - x86_64
    variants:
      - default

  - generator: hostname
    path: /etc/hostname

  - generator: hosts
    path: /etc/hosts

  - generator: remove
    path: /root/file

  - generator: template
    name: foo
    content: |-
      Here goes the content
    template:
      properties:
        key: value
      when:
        - create
        - copy

packages:
  manager: apt
  custom_manager:
    clean:
      cmd: mgr
      flags:
        - clean
    install:
      cmd: mgr
      flags:
        - install
    remove:
      cmd: mgr
      flags:
        - remove
    refresh:
      cmd: mgr
      flags:
        - refresh
    update:
      cmd: mgr
      flags:
        - update
    flags:
      - --yes
  update: true
  cleanup: false
  sets:
    - packages:
        - gnupg
      action: install
      early: true

    - packages:
        - vim
      action: install
      releases:
        - a
        - b
      architectures:
        - x86_64
      variants:
        - default

    - packages:
        - lightdm
      action: install
      flags:
        - --no-install-recommends

    - packages:
        - grub
      action: remove

  repositories:
    - name: reponame
      url: |-
        deb http://archive.ubuntu.com/ubuntu {{ image.release }}-updates main restricted universe multiverse
      type: type
      key: 0xdeadbeaf
      releases:
        - a
        - b
      architectures:
        - x86_64
      variants:
        - default

actions:
  - trigger: post-unpack
    action: |-
      #!/bin/sh

      do something after the rootfs has been unpacked

  - trigger: post-files
    action: |-
      #!/bin/sh

      do something after the files section has been processed

  - trigger: post-update
    action: |-
      #!/bin/sh

      do something after packages have been processed

  - trigger: post-packages
    action: |-
      #!/bin/sh

      do something after the packages section has been processed

    releases:
      - a
      - b
    architectures:
      - x86_64
    variants:
      - default

mappings:
  architectures:
    a: b
    c: d
  architecture_map: debian

environment:
  clear_defaults: true
  variables:
    - key: FOO
      value: bar

lxc/lxc-ci/images/alpine.yaml

image:
  distribution: "alpinelinux"

source:
  downloader: alpinelinux-http
  same_as: 3.12
  url: https://mirror.csclub.uwaterloo.ca/alpine/
  keys:
  # 0482D84022F52DF1C4E7CD43293ACD0907D9495A
  - |-
    -----BEGIN PGP PUBLIC KEY BLOCK-----

    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
    bcgRRcklNr8mTzJH
    =ckew
    -----END PGP PUBLIC KEY BLOCK-----

targets:
  lxc:
    create_message: |
      You just created an {{ image.description }} container.

    config:
    - type: all
      before: 5
      content: |-
        lxc.include = LXC_TEMPLATE_CONFIG/alpine.common.conf
    - type: user
      before: 5
      content: |-
        lxc.include = LXC_TEMPLATE_CONFIG/alpine.userns.conf
    - type: all
      after: 4
      content: |-
        lxc.include = LXC_TEMPLATE_CONFIG/common.conf
    - type: user
      after: 4
      content: |-
        lxc.include = LXC_TEMPLATE_CONFIG/userns.conf
    - type: all
      content: |-
        lxc.arch = {{ image.architecture_personality }}
  incus:
    vm:
      filesystem: ext4

files:
- path: /etc/hostname
  generator: hostname

- path: /etc/hosts
  generator: hosts

- generator: fstab
  types:
  - vm

- generator: incus-agent
  types:
  - vm

- path: /etc/default/grub
  generator: dump
  pongo: true
  content: |-
    # Set the recordfail timeout
    GRUB_RECORDFAIL_TIMEOUT=0

    # Do not wait on grub prompt
    GRUB_TIMEOUT=0

    # Set the default commandline
    GRUB_CMDLINE_LINUX_DEFAULT="console=tty1 console=ttyS0 modules=sd-mod,usb-storage,{{ targets.incus.vm.filesystem }} rootfstype={{ targets.incus.vm.filesystem }}"

    # Set the grub console type
    GRUB_TERMINAL=console

    # Disable os-prober
    GRUB_DISABLE_OS_PROBER=true
  types:
  - vm

- path: /etc/network/interfaces
  generator: dump
  content: |-
    auto eth0
    iface eth0 inet dhcp
    hostname $(hostname)

- path: /etc/inittab
  generator: dump
  content: |-
    # /etc/inittab
    ::sysinit:/sbin/openrc sysinit
    ::sysinit:/sbin/openrc boot
    ::wait:/sbin/openrc default

    # Set up a couple of getty's
    ::respawn:/sbin/getty 38400 console
    tty1::respawn:/sbin/getty 38400 tty1
    tty2::respawn:/sbin/getty 38400 tty2
    tty3::respawn:/sbin/getty 38400 tty3
    tty4::respawn:/sbin/getty 38400 tty4

    # Stuff to do for the 3-finger salute
    ::ctrlaltdel:/sbin/reboot

    # Stuff to do before rebooting
    ::shutdown:/sbin/openrc shutdown

- path: /etc/inittab
  generator: template
  name: inittab
  content: |-
    # /etc/inittab
    ::sysinit:/sbin/openrc sysinit
    ::sysinit:/sbin/openrc boot
    ::wait:/sbin/openrc default

    # Set up a couple of getty's
    ::respawn:/sbin/getty 38400 console

    # Stuff to do for the 3-finger salute
    ::ctrlaltdel:/sbin/reboot

    # Stuff to do before rebooting
    ::shutdown:/sbin/openrc shutdown

- name: meta-data
  generator: cloud-init
  variants:
  - cloud

- name: network-config
  generator: cloud-init
  content: |-
    version: 1
    config:
    - type: physical
      name: eth0
      subnets:
      - type: dhcp
        control: auto
  variants:
  - cloud

- name: user-data
  generator: cloud-init
  variants:
  - cloud

- name: vendor-data
  generator: cloud-init
  variants:
  - cloud

packages:
  manager: apk
  update: true
  cleanup: true
  sets:
  - packages:
    - alpine-base
    - logrotate
    - doas
    action: install

  - packages:
    - cloud-init
    - openssh
    - e2fsprogs-extra
    action: install
    variants:
    - cloud

  - packages:
    - py3-pyserial
    - py3-netifaces
    action: install
    variants:
    - cloud
    releases:
    - 3.17
    - 3.18
    - 3.19
    - 3.20
    - edge

  - packages:
    - acpi
    - gcc
    - grub-efi
    - linux-virt
    - udev
    action: install
    types:
    - vm

actions:
- trigger: post-packages
  action: |-
    #!/bin/sh
    set -eux

    rm -f /var/cache/apk/*

- trigger: post-packages
  action: |-
    #!/bin/sh
    set -eux

    # Rewrite configuration for LXC
    sed -i 's/#rc_sys=""/rc_sys="lxc"/' /etc/rc.conf

    # Honor fstab by not making the localmount script a noop
    sed -i 's/-lxc//' /etc/init.d/localmount

    # Enable services
    for svc_name in bootmisc syslog devfs; do
        ln -s /etc/init.d/${svc_name} /etc/runlevels/boot/${svc_name}
    done

    for svc_name in networking crond; do
        ln -s /etc/init.d/${svc_name} /etc/runlevels/default/${svc_name}
    done
  types:
  - container

- trigger: post-files
  action: |-
    #!/bin/sh
    set -eux

    for svc_name in acpid bootmisc hostname hwclock loadkmap modules networking swap sysctl syslog urandom; do
        ln -fs /etc/init.d/${svc_name} /etc/runlevels/boot/${svc_name}
    done

    for svc_name in devfs dmesg hwdrivers mdev udev udev-settle udev-trigger; do
        ln -fs /etc/init.d/${svc_name} /etc/runlevels/sysinit/${svc_name}
    done

    target=/boot/grub/grub.cfg
    grub-mkconfig -o "${target}"
    sed -i "s#root=[^ ]*#root=${DISTROBUILDER_ROOT_UUID}#g" "${target}"

    TARGET="x86_64"
    [ "$(uname -m)" = "aarch64" ] && TARGET="arm64"
    grub-install --target=${TARGET}-efi --no-nvram --removable
    grub-install --target=${TARGET}-efi --no-nvram

    # Attempt to correct errors in the installation of all packages.
    apk fix
  types:
  - vm

- trigger: post-files
  action: |-
    #!/bin/sh
    set -eux

    for svc_name in sshd; do
        ln -fs /etc/init.d/${svc_name} /etc/runlevels/default/${svc_name}
    done

    # Tweak to prevent cloud-init from getting stuck.
    echo "datasource_list: ['NoCloud', 'ConfigDrive', 'LXD', 'None']" > /etc/cloud/cloud.cfg.d/99_lxc.cfg
  types:
  - vm
  variants:
  - cloud

- trigger: post-files
  action: |-
    #!/bin/sh
    set -eux

    setup-cloud-init
  variants:
  - cloud

mappings:
  architecture_map: alpinelinux

为Incus构建Distrobuilder

Wed, 07 Aug 2024 16:00:00 +0800

Distrobuilder作为构建Incus/LXC容器镜像的主要工具，竟然只通过Snap商店提供预编译的二进制包。

岂有此理，让我们设置一个Distrobuilder构建环境吧！一切其实很简单！

启动基础容器

当然，构建一系列动作都可以在本机上直接进行。如果决意如此，请自动忽略本文中容器相关的操作。

不过，Distrobuilder是用Golang编写的程序，因此我们完全可以在容器中构建完成后，移动到主机系统中运行。

既然，构建生成的可执行文件要在主机系统中运行，那当然更推荐设置一个和主机系统相符或接近的容器环境。

例如，我的主机系统是Debian，那么现在一个Debian容器构建环境将具备更好的兼容性。

`1`	`incus launch images:debian/12 go-dev`

安装容器基础软件

由于Debian Bookworm中的golang-go软件包版本号过低，不满足distrobuilder的最低要求版本1.21，因此需要先安装好系统基础组件，稍后自行下载golang编译器。

cat <<EOF | incus exec go-dev /bin/bash
sed -i 's/deb.debian.org/mirrors.bfsu.edu.cn/g' /etc/apt/sources.list
apt-get update
apt-get -y install debootstrap rsync gpg squashfs-tools git make build-essential
EOF

🚨 注意

不要遗漏构建基础套件
对于手动安装golang编译器的用户，请务必记得安装build-essential或其他构建基础套件！

安装Golang套件

cat <<EOF | incus exec go-dev -- /bin/bash
rm -rf /usr/local/go && wget -qO- https://go.dev/dl/go1.22.5.linux-amd64.tar.gz | tar xz -C /usr/local
echo 'export PATH=\$PATH:/usr/local/go/bin' >> /root/.bashrc
EOF

如有需要，可以将上述下载链接更换为镜像站链接。

获取distrobuilder源代码

直接前往Releases - lxc/distrobuilder下载最新的源代码包。

如果在本机上下载完成了，可以推送到容器中：

`1`	`incus file push distrobuilder-distrobuilder-3.0.tar.gz go-dev/root/`

执行incus exec go-dev -- /bin/bash进入容器，接着执行：

mkdir -p $HOME/go/src/github.com/lxc/
cd $HOME/go/src/github.com/lxc/
tar xzf /root/distrobuilder-distrobuilder-3.0.tar.gz
mv distrobuilder-distrobuilder-3.0 distrobuilder

配置go语言资源代理（可选）

以南京大学镜像站为例：

1
2

go env -w GO111MODULE=on
go env -w GOPROXY="https://repo.nju.edu.cn/go/,direct"

开始编译！

1
2

cd distrobuilder/
make

试运行

1
2

cd ~/go/bin/
./distrobuilder --help

若能成功运行，就可以拉回本机使用了。需要回到主机运行：

`1`	`incus file pull go-dev/root/go/bin/distrobuilder .`

容器也可以随之摧毁：

`1`	`incus delete go-dev -f`

Incus/LXD文件系统挂载与访问

Wed, 07 Aug 2024 12:00:00 +0800

当我们使用容器时，时常希望容器能挂载访问本地文件系统。例如，Docker可以将本地路径挂载为一个Volume访问。

Incus/LXD当然也提供了这一功能，但配置起来却有时略显复杂。

只读挂载

非常简单：

`1`	`incus config device add <container-name> <device-name> disk source=/path/on/host path=/path/in/container`

读写权限

然而，以上命令挂载的目录，在容器中常常只有只读权限。

这是因为，Incus非特权容器会默认将容器进程映射到不同的非特权UID/GID运行。

为了让容器内进程也能读写目录，常常可以采用下列方法。

方法1：shift选项

在添加挂载配置时，使用shift=true选项挂载，即可将容器中UID/GID映射到主机文件系统，命令如下：

`1`	`incus config device add <container-name> <device-name> disk source=/path/on/host path=/path/in/container shift=true`

这种方法看上去是最为便捷的，简洁，不需要额外配置。然而，这种方法的局限性与麻烦隐藏在背后。

Restricted path

在Debian/Ubuntu上，当属于incus组且不属于incus-admin组的用户访问Incus时，Incus会为用户创建一个独立的Incus项目(Project)，并限定用户的所有访问资源都位于这一项目下。

显然，这种设计增强了系统安全性，然而，需要注意到，这个项目是资源受限的。很不幸地，挂载主机文件系统同样在限制范围内。

此时，如果用户执行上述含有shift=true选项的挂载命令，会出现以下报错：

`1`	`Error: Failed to start device "my-vol": The "shift" property cannot be used with a restricted source path`

具体来说，在普通用户Incus项目中，Restricted选项会限制挂载的源路径。可以参考Project配置文档进一步了解。

那么，如何在坚持使用shift=true选项的前提下挂载目录呢？

最简单的方法之一是，使用root身份修改用户项目配置：

`1`	sudo incus project edit user-1000`

找到restricted.devices.disk.paths一行，将后面的路径删除，留下一对空白的双引号即可。

1
2

- restricted.devices.disk.paths: /home/xxx
+ restricted.devices.disk.paths: ""

安全隐忧

如果上述问题只是多了一个额外的步骤，修改完项目配置就一劳永逸了。那么接下来的问题恐怕能让安全人员睡不着觉。

当shift=true时，容器向挂载目录写入的文件，其用户组信息都将与容器中用户组保持一致！！！

例如，假设在容器的挂载路径中有一test.txt文件，如果其拥有者是root:root（当然也可以在容器中以root身份设置所有权），此时回到主机文件系统，test.txt文件的拥有者将会是主机上的root:root！

在这种情况下，任何一个拥有了不受挂载目录限制的，具备incus组身份的用户，都等价于拥有了主机上的root权限。

又或者，拥有容器root权限的，且能以主机上任意一个用户身份执行特定可知路径可执行文件的用户，都等价于拥有了主机上的root权限。

很可怕吗？是的很可怕。

⚠️ 警告

威胁的来源？
大体来说，任何具备了容器内root权限的人，都可以向挂载路径中以root身份写入可执行文件，并设置setgid属性与777权限。

此时只需要再在主机上获得任一用户shell，执行挂载路径中的可执行文件并setgid系统调用，即可获得root权限。

相比之下，这一问题就显得更加棘手了。

目前比较适合的解决方案是，在容器中创建非特权用户以执行代码，像保护主机root用户一样保护容器root用户。

但，恐怕大家都会同意的是，到这一步为止，一切都显得有些复杂了。

方法2：UID与GID映射

另一种方法显得较为传统，当然也是在网上最容易找到的方案，也就是将容器中的进程UID与GID，映射为主机上某一用户的UID与GID，从而赋予容器进程“扮演”该用户访问文件系统，从而达到读写主机文件的目的。

这一方法的好处是，可以非常方便地保证，容器进程对挂载文件目录的权限，与主机系统上特定角色的权限保持一致。常见的场景是：

如果希望容器访问我们的~家目录，只需要赋予容器和我们账户一样的UID与GID，再将我们的~挂载到容器中，剩下的事情就是一切如常了。
如果希望容器按照我们想要的权限，例如只读地访问一些文件，我们可以将容器里的用户组映射到本机某一用户组上，容器中的进程也将获得被映射到的组的文件系统权限，例如www-data等。

让我们直接参考Incus/LXD主要开发者的博客吧。

配置subuid与subgid

这里的第一步是，需要把希望容器映射到的用户ID和组ID，设置为允许Incus主进程，也就是root用户使用，从而让Incus能“扮演”我们用户账户。

如果只是想让Incus扮演我们当前使用的账户，访问我们当前账户能访问的资源，那么只需要执行以下命令：

1
2

printf "root:$(id -u):1\n" | sudo tee -a /etc/subuid
printf "root:$(id -g):1\n" | sudo tee -a /etc/subgid

现在，让我们重启Incus，让配置生效：

`1`	`sudo systemctl restart incus`

接下来是具体说明，不想看的可以略过。

实际上，这一步配置主要是向/etc/subuid和/etc/subgid文件添加类似下方的一行。

`1`	`root:1000:1`

这一句配置的意思是，允许root用户/组映射UID与GID，而映射的目标UID/GID范围从1000开始，root可以使用接下来的1个UID/GID，也就是1000这一个UID/GID。具体可以按需调整。

配置Incus容器

还差最后一步！我们现在需要让容器使用刚刚指定的UID与GID，真正开始扮演指定的用户或组。

依然是省流，如果只是希望test容器中的root用户(UID/GID均为0)扮演我们当前使用的账户，请直接执行：

`1`	`printf "uid $(id -u) 0\ngid $(id -g) 0" \| incus config set test raw.idmap -`

接下来是详细解释。以上命令会在容器实例的配置文件中出现类似于下面的一段：

config:
  raw.idmap: |-
    uid 1000 0
    gid 1000 0

这段配置的意思非常直观：将本机上的UID1000，映射成容器中的UID0。同理对GID也进行这一映射。

这一段配置使得容器中的root用户，实际上具备了主机中UID为1000用户的权限，因此，容器中以root身份执行的程序，实际上是以本机UID为1000的用户身份执行的。

📝 备注
能否在容器中使用其他用户身份？
当然可以！在上面的配置中，每一行末尾的0即表示容器中root用户的UID与GID。

如果希望映射成容器中的其他用户，假设容器内用户的UID和GID是10086，那么只需要将刚刚的命令修改成：
1
printf "uid $(id -u) 10086\ngid $(id -g) 10086" | incus config set test raw.idmap -
就可以将容器内的10086用户映射成主机上的当前用户了。

现在，我们就可以像设置只读挂载一样，将本地路径挂载到容器中，不再需要shift=true选项。

`1`	`incus config device add <container-name> <device-name> disk source=/path/on/host path=/path/in/container`

至此，我们终于能让Incus容器，在保持正确权限的同时，读写主机上挂载的文件目录。

Docker镜像本地拉取与迁移

Sat, 29 Jun 2024 12:00:00 +0800

由于网络连通性原因，DockerHub的访问变得困难。然而在服务器上部署服务时，又经常需要使用Docker。

为了避免在服务器上进行复杂的网络设置，一种相对折中的方法是：在一台网络流畅（下面称为本机）的机器上获取Docker镜像，再将镜像复制到服务器上使用。

工具 - Skopeo

一种传统的方法是，在本机上也安装一个Docker Engine，使用docker pull命令拉取镜像，再使用docker save导出镜像。

这种方法的缺点在于，我们在本机上或许并不需要/不想要/难以安装Docker引擎。

而维新派指出，在Docker引擎官方代码仓库moby/moby/contrib下，有一个download-frozen-image-v2.sh脚本，该脚本提供了对Docker镜像的下载功能。听起来不错？

而当然，也有更便捷的工具：containers/skopeo。这也是本文介绍的主角。

安装Skopeo

安装skopeo相当简单，例如在Debian 11+/Ubuntu 20.10+内，可以直接在apt源中下载安装。Alpine Linux同样可以使用apk直接添加。

尽管skopeo不支持Windows版本，但完全可以创建一个简易的Alpine Linux WSL环境完成以上任务。

使用Skopeo获取镜像

主要使用的是skopeo copy命令，文档参见skopeo/docs/skopeo-copy.1.md。

具体来说，在拷贝时，我们常常希望把镜像打成一个tar包，可以方便地在网络上传输。skopeo可以直接导出tar文件，具体如下：

`1`	`skopeo copy docker://<image>:<tag> docker-archive:/path/to/archive.tar:<image>:<tag>`

例如，如果想要拉取busybox的最新版本镜像busybox:latest，可以执行：

`1`	`skopeo copy docker://busybox:latest docker-archive:myarchive.tar:busybox:latest`

如果镜像是由非Docker官方发布的，镜像名称中会含有斜杠，请放心，此时镜像名称<image>就是包含斜杠的完整字符串。例如，以下命令当然是没问题的。

`1`	`skopeo copy docker://bitnami/postgresql:14 docker-archive:/path/to/archive.tar:bitnami/postgresql:14`

值得注意的是，在上述命令里，附加在打包文件名后的<image>:<tag>，即为之后导入docker时，该镜像所关联到的名称。

例如，如果执行：

`1`	`skopeo copy docker://busybox:latest docker-archive:myarchive.tar:busybox:10086`

导入到docker中的镜像名称也会被显示为busybox:10086：

1
2
3

user@server:~$ docker images                                                                                                                 
REPOSITORY    TAG          IMAGE ID       CREATED         SIZE                                                                         
busybox       10086        1234567890ab   1 months ago   1.23MB

打包后，为了节约传输带宽和时间，可以对打包好的tar文件压缩一下。可以使用zstd（gz等当然也行），大约能缩小2/3的体积。

`1`	`zstd -9 myarchive.tar`

在服务器上导入镜像

使用喜欢的方法将打包文件传输到服务器后，就可以导入Docker引擎：

`1`	`docker load < myarchive.tar.zstd`

这里使用的是重定向输入文件流，当然也可以使用-i参数引导读取指定路径的文件。同时，docker load也可以加载包括gz, xz, bzip2, zstd在内的压缩文件。

与同名同tag现有镜像的冲突

导入时会覆盖掉同名镜像，即原有镜像的名称会被置空，变成孤立的镜像。运行docker images prune可以删除这些孤立镜像。

龙芯小试 —— 龙芯3A3000主机简单配置与Debian系统安装

Sat, 19 Mar 2022 10:53:24 +0800

前言

前几天在咸鱼上买到了一块龙芯的电脑主板，CPU型号是龙芯(Loongson) 3A3000，芯片组似乎是780E。回来装系统的时候遇到了不少麻烦，这里记录一下，如果能帮到后来者，那自然是最好不过。

系统选择

实际上，我仍然推荐有条件的用户，使用龙芯官方适配的操作系统Loongnix，因为这是龙芯优化过的系统。

只不过，因为mips64el架构上的Loongnix是基于Fedora发行版的，且版本古老。我个人习惯的环境是Debian，只有LoongArch上的Loongnix才是基于Debian制作的。况且，Loongnix默认带一个GUI，连服务器版都带，我不是很喜欢先装后卸，因此我还是希望安装一个相对干净的Debian系统上去。

龙芯3A3000基于mips架构，具体到Debian上，属于mips64el架构（MIPS 64-bit little-endian mode, MIPS 64位小端序），请记住这个代号，因为我们后面会反复用到。

关于Debian的系统代号选择，在本文编写时，最新的Debain系统是Debian 11 Bullseye，使用的系统内核是Linux 5.10. 但我们目前会使用上一个版本，也就是Debain 10 Buster，具体原因下面会说明。

下面我们讨论的方法，基于狗剩百科:Debian 系发行版安装指南，并做一些自己经验的额外补充。

条件限制和实现方式

安装方式的选择

在平时x86计算机上，安装Debian的方法，首选当然是直接从Debian CD源中下载安装镜像，将镜像刻录到U盘上，引导镜像中的安装程序完成安装。这样当然是最简单的。

然而，根据我的简单测试，似乎Debian CD源中的ISO镜像，并不能顺利地在我手头上这块主板中引导。

📝 失败的Debian安装程序引导测试

这一段是我尝试在龙芯上引导Debian安装镜像时的失败操作，或许是该镜像不具备在龙芯电脑上引导的能力，也有可能是我本身操作方法不正确。因此我将这一过程记录在此，如有谬误，还请批评指正。如果您希望参考本文进行Debian系统的安装，请略过这一段。

下载Debian CD中的安装镜像debian-11.2.0-mips64el-netinst.iso

使用dd命令，将其刻录到U盘上: dd if=debian-11.2.0-mips64el-netinst.iso of=/dev/sdb bs=8M，（其中/dev/sdb是我的U盘设备）

将U盘插入龙芯电脑，启动，提示找不到LiveCD中的一个文件。

根据上述表现，个人猜测电脑已经成功读取并加载了U盘上的引导程序，但不知为何无法加载U盘上的后续文件，无法进入安装程序。

此外，目前我个人还暂时无法确定这块龙芯主板究竟是BIOS/CSM引导模式还是EFI引导模式。BIOS设定中无对应选项可调整。

在龙芯提供的Loongnix镜像中，存在一个EFI文件夹，且引导该Loongnix镜像时，在GRUB Shell中执行echo $grub_platform，回显结果为efi。且在Loongnix LiveCD系统中，grub-install命令提示安装的平台为MIPS下的EFI平台。

但进入该LiveCD系统后，使用Loongnix的安装程序尝试安装系统时，如果磁盘为GPT分区表，会提示当前计算机运行在BIOS/CSM模式下，需要创建额外分区才能继续安装。采用MS-DOS分区表则无此问题，安装时不需要创建ESP分区也可完成安装并正常引导本地磁盘系统。这也是我电脑目前的状态。

因此，我已经无法区分这台龙芯电脑运行在何种模式下，需要进一步考察。如果您有什么看法或观点，欢迎通过邮件同我交流，我的电子邮件地址在站内可找到。

有些难办的是，mips64el的Debian源，没有GRUB2软件包提供！ 这就意味着，我们需要借助其他方法，安装GRUB引导器 —— 如果没有GRUB引导器，我们是无法引导我们的系统的！

因此，我们需要另辟蹊径，分两步安装Debian系统：

安装龙芯的Loongnix系统到本地硬盘上。我选用的镜像是loongnix-20180930.iso。这一步骤主要目的是借助官方的安装程序，完成分区并将GRUB与Linux内核安装到本地硬盘。
重新进入LiveCD系统，删除本地硬盘中原有的根目录结构 （但需要保留/boot目录下的所有内容！因此建议在第一步安装Loongnix系统时，将/boot作为一个独立的分区，空间大约1GB）
使用debootstrap工具，创建Debian根文件系统，并在此基础上，进行修改。更多相关的信息可以阅读通过 Unix/Linux 系统来安装 Debian GNU/Linux。

总体而言，我们相当于借用了Loongnix系统提供的内核引导Debian系统。大部分情况下，这种方法没有问题，但也有一些情况下，系统中的部分程序要求Linux内核版本号高于一个指定版本。此时需要自行斟酌是否升级，升级到何版本。本文后面会讨论这一问题。

Debian大版本号的选择

不同Debian大版本号下，对应的Linux内核版本号也不同。原则上讲，我们使用的内核版本号应该接近Debian官方指定的内核版本号。在Debian软件源中，龙芯3代CPU使用的内核包名为linux-image-loongson-3。

Debian版本号	Debian代号	软件源中使用的内核版本号
9	stretch	4.9
10	buster	4.19
11	bullseye	5.10

此外，北京龙芯也有提供一些预编译的Debian格式内核包：https://mirrors.tuna.tsinghua.edu.cn/bjlx/pool/main/l/，我目前使用的是其提供的linux-4.19.0-loongson-3下的包。暂时不清楚北京龙芯提供的内核包相对于Debian提供的包是否有特别的优化，或其他区别。

选用Linux 4.19内核的前提下，Debian 10就成为了适配的最佳选择。

过段时间我会尝试下是否能直接用Debian 11 + Linux 5.10，届时会更新后续。

📝 备注

后续1: 2022年4月11日下午

根据我的简单测试，Debian维护者打包的Linux 5.10内核，虽然可以正常工作，但似乎和我手上这块780E主板有点不相兼容。

具体表现为，开机后风扇非常嘈杂，怀疑是有一部分功能没能成功移交给操作系统。过段时间再试试看吧。

安装流程

准备

🚨 注意

备份文件警告！

请务必在执行后续操作前，备份目标计算机上的所有重要文件！本人不会对您任何操作/误操作造成的损失负责！

一个空白U盘，用于刻录LiveCD镜像
Loongnix LiveCD镜像，我选用的版本为loongnix-20180930.iso（实际上这个版本有些不好用，因为其基于Fedora 21构建，软件包版本非常老，如果有新版本的Loongnix LiveCD在你的电脑上可用，完全可以替换）。
有效的网络连接（这要求第二步中的镜像可以正常驱动网卡）

同时，下面的操作几乎都是在root权限中完成的。

刻录LiveCD镜像并引导

我想这一步会是大伙比较熟悉的了。

`1`	`dd if=loongnix-20180930.iso of=/dev/sdX bs=8M`

of=/dev/sdX部分，请替换成你的U盘实际设备块，如/dev/sdb。不清楚的可以使用fdisk -l查看。

写入完成后，将U盘插到龙芯电脑上，开机并从U盘引导。

安装debootstrap

进入LiveCD环境后，首先配置好网络。接着安装debootstrap。可以使用命令dnf install debootstrap从Fedora源中下载安装。如果源中的工具太老不方便，也可以直接从Debian软件源中下载debootstrap的.deb包，使用tar与ar将其解压即可使用该程序（在Loongnix/Fedora上也可以！）

挂载目标分区

接下来，随便在根目录下创建一个新路径，例如/deb，用于挂载我们的本地磁盘分区。

接着，将本地磁盘上，已经安装有Loongnix的根目录分区，挂载到挂载点上。但此时先不需要挂载/boot分区。如果真的需要挂载boot，请在删除时选择忽略/boot下的所有文件！

挂载之后，删除该分区下的所有文件

下面的例子，我们假设本地磁盘上，/dev/sda1是/boot分区，/dev/sda2是/分区，/dev/sda3是swap分区。

1
2
3

mkdir /deb
mount /dev/sda2 /deb
rm -rf /deb/*

执行安装程序

接下来，我们要用debootstrap创建一个Debian根文件系统。

1
2

debootstrap --arch mips64el buster \
     /deb http://ftp.cn.debian.org/debian

最后的地址可以替换成你所在位置速度最快的Debian镜像地址。

如果debootstrap提示找不到一个名称中包含buster的配置文件，可能是当前使用的debootstrap工具版本太老（常见于使用Fedora源安装）。一种解决方法是下载新版的debootstrap工具，另一种是直接使用Debian的相对代号，如在本文编写时，Debian 10 Buster是上一个稳定版，则可以使用oldstable替代buster。同理，如果使用旧版的debootstrap安装Debian 11 Bullseye报错，也可以使用stable替代bullseye。

坐下来，等一等，喝杯咖啡，根文件系统就创建好了。

基础系统配置

为了让系统能跑起来，单有个根文件系统是完全不够的。

复制内核模块

虽然这么做不知道是否合适，可以考虑试试。

将Loongnix的内核模块，复制到目标Debian系统中。

`1`	`cp -r /lib/modules /deb/lib/`

fstab文件

/etc/fstab文件指定了系统启动时挂载文件目录的规则，需要仔细配置。

编写该文件，可以自己亲历亲为，仔细编写即可。但懒人有懒人的方法，不喜欢自己写这种配置文件，怕出错的话，也完全可以用ArchLinux团队提供的genfstab脚本，自动生成配置文件。方法也非常简单，可以去人家Github主页GitHub - archlinux/arch-install-scripts: Useful scripts for installing Arch Linux 直接下载源码包，make一下就好。或者，现在包括Debian在内的发行版仓库也包含了这个脚本的可执行文件，下载解压运行一气呵成。

使用genfstab，需要在LiveCD操作系统中运行，且需要在运行前将/boot分区挂载到Debian系统的/boot上，物归原主。如果有swap分区的话，也需要确认已经启用。

`1`	`mount /dev/sda1 /deb/boot`

确认无误后，就可以使用下面的命令生成fstab文件了。

`1`	`genfstab -U /deb > /deb/etc/fstab`

-U参数是指定使用UUID作为分区识别的标准。/deb是Debian根文件系统的挂载点，最后的重定向是将输出写入到目标系统的/etc/fstab中。

建议生成后自行检查一下文件是否符合预期。

chroot环境

还需要chroot进入Debian系统，对其进行一些配置。

`1`	`LANG=C.UTF-8 chroot /deb /bin/bash`

设置root口令

`1`	`passwd root`

安装常用软件包

或许下列软件包会提供一些提示，具体是否需要可以看您的需求。

locales: 使用英语以外的语言必须的软件包
vim/emacs/nano: 文本编辑器
openssh-server: SSH服务器，使用SSH登录系统的必须
build-essential: Debian下用于构建软件包的套件，包含了gcc/g++/make等工具
network-manager: Network Manager工具，可以自动配置网络

安装这些软件包只要用apt工具即可。如：

`1`	`apt install locales vim build-essential`

网络配置

网络配置是一件烦人的事情，人生或许应该用在更有意义的事情上。因此我个人喜欢用Netowork Manager自动接管网络配置。

`1`	`apt install network-manager`

还有什么比开机就能看到有线网络已连接，无线网络只需要一行命令就可连接，更令人开心的事情吗？

当然，如果你喜欢其他方法，如直接编辑/etc/network/interfaces，那也可以参考对应的教程。

此外，我们还需要配置hostname，也就是本机的主机名。

`1`	`echo myloong > /etc/hostname`

完成

我想上述配置已经可以让Debain系统跑起来了。退出chroot环境，重启电脑，记得拔掉U盘，没有意外的话，就可以进入Debian系统了。

如果电脑引导卡在Loongnix字样的引导动画，不妨尝试按下 Ctrl + Alt + F2 （F2~F8都可以试试），看能否见到熟悉的登录界面。

更换内核

如果你阅读到这里，看起来你已经进入了Debian系统，那么先恭喜你，你的Debian系统已经可以使用了！

但问题随之而来，如果你使用的Loongnix镜像和我相同，那你一定会发现，Loongnix使用的内核版本较老，可能是3.10附近的版本。而即便使用Fedora 28，其内核版本号也约为4.4~4.9左右的版本，和Debian官方的内核版本号是不匹配的。对于强迫症来说，这样的情况不太爽，我们得想想办法替换内核！

备份

然而，这样的操作注定是危险的，经常失败的，我想在进行下述操作前，需要先将系统备份一次。毕竟从debootstrap安装系统的流程终究繁琐，值得创建一个小小的备份帮助我们快速恢复。

具体备份的方法就不展开了。数据备份的责任在各位操作者本身！

安装新内核

安装新版本内核的方法有许多，Debian官方软件源中的会是一个选择。不过既然我没用过，那我也不具体展开介绍了。反正安装方法极为简单，apt install linux-image-loongson-3 linux-headers-loongson-3 linux-libc-dev就可以了。

我们接下来介绍怎么安装北京龙芯提供的4.19.0内核包。

下载地址位于https://mirrors.tuna.tsinghua.edu.cn/bjlx/pool/main/l/linux-4.19.0-loongson-3/，需要下载该地址下的三个文件：

可以考虑将三个文件下载到同一个文件夹中。随后进入该文件夹，执行

`1`	`dpkg -i *.deb`

即可安装三个软件包。

更新initramfs

首先安装initramfs-tools软件包

`1`	`apt install initramfs-tools`

执行下述命令，更新initramfs

`1`	`update-initramfs -k 4.19.0-loongson-3 -u -v`

这会在/boot下生成一个initrd.img-4.19.0-loongson-3文件。我们接下来配置GRUB引导项会使用到这一文件。

修改GRUB配置文件

最后一步，修改GRUB配置文件。

📝 失败的GRUB配置生成

这一部分我也不确定最佳做法是什么，因此还请熟悉GRUB的同学批评指正！

众所周知，在x86平台下，每次更新内核后，只需要使用grub-mkconfig命令，即可自动生成正确的GRUB配置文件。

尽管Debian MIPS64EL软件源不提供GRUB2软件包，但提供了grub-common软件包，其包含了grub-mkconfig命令。因此我尝试使用该程序为新内核创建引导菜单。就生成的结果看，其生成确实正常。

但在重启引导时，GRUB提示insmod命令无法找到。

这是很奇怪的事情，因为无论是原Loongnix生成的grub.cfg还是Debian生成的grub.cfg，都使用了insmod命令。

目前我尚未弄清楚造成该问题的原因，正在比较两配置文件的差异，还请大家批评指正。

这里，我们使用的方法是，直接修改原有的/boot/grub.cfg文件，将原先引导的3.x内核文件，改为新安装的4.19内核文件。

menuentry 'Loongnix GNU/Linux' --class loongnix --class gnu-linux --class gnu --class os --unrestricted $menuentry_id_option 'gnulinu$        set root='hd0,msdos1'
        if [ x$feature_platform_search_hint = xy ]; then
          search --no-floppy --fs-uuid --set=root --hint-ieee1275='ieee1275//disk@0,msdos1' --hint-bios=hd0,msdos1 --hint-efi=hd0,msd$
        else
          search --no-floppy --fs-uuid --set=root b6a3a91c-82b0-4ac6-ba62-19a9d4cf63c7
        fi
-        echo    'Loading Linux 3.10.84-20.fc21.loongson.3.mips64el ...'
-        linux   /vmlinuz-3.10.84-20.fc21.loongson.3.mips64el root=/dev/sda2 ro rhgb quiet loglevel=0 LANG=zh_CN.UTF-8
-        initrd /initramfs-3.10.84-20.fc21.loongson.3.mips64el.img
+        echo    'Loading Linux 4.19.0-loongson-3 ...'
+        linux   /vmlinuz-4.19.0-loongson-3 root=/dev/sda2 ro rhgb quiet loglevel=0 LANG=en_US.UTF-8
+        initrd /initrd.img-4.19.0-loongson-3
        boot
}

编辑后，保存该文件，重启，至少在我的电脑上，这种方法成功替换了系统内核。

目前我还没探索到更优雅地生成GRUB配置文件的方法，如果您有好的想法或见解，欢迎给我发邮件，敬请批评指正。

可能的改进方法

这部分主要是我暂时的改进想法，如果您是参考本文安装Debian系统，或许可以跳过这一段落了。

很明显，两种GRUB配置文件中，有部分insmod命令没有正常执行。

一种解决方法是，每次安装内核，都通过自己手动修改/boot/grub.cfg文件，达到引导新内核的目的，缺点是不优雅，容易出错。

另一种解决方法是，我们都知道，GRUB配置文件的生成是基于/etc/grub.d/下的模板文件的，那么可以考虑将Loongnix系统中的模板文件复制到Debian中，即可生成格式接近的配置文件，或许也可以解决问题。

但目前头疼的问题还有，Debian不提供MIPS64EL架构的GRUB2包，导致必须依赖Loongnix/Fedora安装GRUB主引导记录。我在尝试自行编译GRUB，具体测试情况可能得等下一篇博文更新了。

尾声

目前经过几天的使用，龙芯3A3000整体还是超过了我的预期的。基本上，3A3000接近于英特尔J1900水准。据说使用LoongArch架构的3A5000性能上了几个台阶，或许今后有机会可以试试看。

我会更期待，我们有更多的实干家出现。

使用WSL创建精简的Hexo写作环境

Wed, 29 Dec 2021 16:44:23 +0800

这篇文章将介绍一种方法，使用Windows Subsystem for Linux (WSL), Alpine Linux发行版, Git等工具，配置一个方便易用的的Hexo博客编写系统。

如果结合已有的网站服务器，还可以使用Git快速进行站点部署与更新。

前言

如您所见，这个网站的渲染生成器是Hexo。众所周知，Hexo是跑在Node.js上的玩意，但npm环境配置是出了名的复杂，甚至在我看来还不是那么优雅，略显混乱，在Windows上更是如此。

过去在Node.js上开发项目，总是避免不了和系统里的npm斗智斗勇，几番折腾，最后竟然无法正常地生成Hexo博客。实际上，也并不是没有考虑过切换博客生成后端，但迁移的成本同样存在，而且选择也较为有限。

不可否认，目前有许多优秀的Node.js管理系统，例如volta之类，但这些工具在Windows下支持也不能算好。而采用Linux作为主桌面？在目前还不能算特别方便。

所以，是否有一种方法，既能有效地管理npm，从而为Hexo创建一个隔离的环境，又能保证整体性能不差，还与Windows轻松兼容呢？

笔者认为，在2021年年底的当下，微软提供的Linux子系统，也就是WSL，是解决这一问题的比较优雅方法。它能满足上面的所有设计要求。以下是具体方法。

预备条件

启用了 Windows Subsystem for Linux 功能的 Windows 10+ 操作系统
Alpine Linux的MINI ROOT FILESYSTEM(最小根文件系统)压缩包，可以在downloads | Alpine Linux找到
其他必须工具，如git等

📝 备注

关于Alpine Linux
Alpine Linux是一个非常精简的Linux发行版，本文编写时，其最新版minirootfs的tar.gz包，仅2.6MB大小，可以在为我们提供尽可能的环境隔离同时，大幅度节省隔离环境所需的额外空间开销。

📝 备注

MINI ROOT FILESYSTEM的作用是?
用于我们手动导入Alpine Linux到WSL中，作为我们的Hexo环境。不过，目前微软商店里已经上架了Alpine WSL应用程序包，和手动导入效果类似，可供选择。如果选择从应用商店安装，请跳过下面导入Alpine Linux一节。

📝 备注

为什么使用Alpine Linux发行版?
Alpine Linux发行版体积比目前绝大多数其他通用的发行版（无论是Debian系还是CentOS系）都要小得多。先前，Alpine由于musl的原因，兼容性不如其他glibc发行版。但后来docker普及之后，许多软件都提供了运行于Alpine Linux的二进制文件。包括Visual Studio Code远程插件，也提供了Alpine Linux的支持。因此，就本文描述的任务而言，选用Alpine Linux是完全没有问题的。

当然，如果更喜欢使用其他发行版，也是完全没有问题的，操作流程和下文整体上还是相同的。注意一下部分命令的替换就好。

导入Alpine Linux

解开GZip包

这一步，我们要导入Alpine Linux系统作为一个WSL的发行版(Distro)。

首先下载Alpine Linux的.tar.gz包，然后用解压工具，解压出.tar包。记住/复制这个.tar包的路径。例如，D:\alpine-minirootfs-3.15.0-x86_64.tar。

⚠️ 警告

注意事项
只需要将压缩包的第一层.gz部分解开，得到里面的.tar包即可。不需要解开.tar包里面的文件系统。

建立目录并导入发行版

在你希望放置这个发行版相关系统文件的地方，创建一个文件夹，这里为了举例子，我们取D:\AlpineHexoBlog。这个路径不一定需要在C盘，可以在你想的合理的位置。名字也是随意的。

接着，我们输入下述命令。

`1`	`wsl --import AlpineHexo D:\AlpineHexoBlog D:\alpine-minirootfs-3.15.0-x86_64.tar --version 2`

这个命令的意思是，将我们解压得到的.tar包，作为一个Linux发行版，导入一个新的发行版，并将相关文件放置在D:\AlpineHexoBlog目录下，这个发行版的名称叫AlpineHexo(这个名字可以随意)，并指定使用WSL版本2（关于WSL1和2的差别，请自行参阅微软官方文档）。

这样，一个自定义的发行版就导入完成了。可以在普通命令行/Powershell里面输入wsl -d AlpineHexo(注意名称替换)进入该发行版的终端。如果电脑装有Windows Terminal，也可以在标签页启动列表中直接选择该发行版。

安装Hexo相关环境

切换到Alpine Linux终端，执行命令。

`1`	`apk add nodejs npm git`

等待安装完成。

安装Hexo

这部分的步骤和Hexo官方文档部分相同，因此直接放出命令如下：

`1`	`npm install -g hexo-cli`

创建博客资源主目录

参考Setup | Hexo。

`1`	`hexo init MyBlog`

上面命令中，MyBlog是可以自定义的文件夹名称，这个文件夹用于存储博客网站的源文件，如站点设置，博客文章原始文件等。在生成渲染网站时，hexo程序会根据这一目录里的配置生成静态网站，我们的大部分操作也都将在这个文件夹里完成。本文剩余部分中，这个目录将称为Hexo主文件夹。

如果输出如下所示，说明创建成功了。

1
2
3

INFO  Cloning hexo-starter https://github.com/hexojs/hexo-starter.git
INFO  Install dependencies
INFO  Start blogging with Hexo!

接着进入这个新文件夹，执行npm install。

1
2

cd MyBlog
npm install

这下，我们的站点就初始化完成了。我们可以任意对这个站点进行自定义，如主题自定义，撰写文章等。

(可选)使用Git管理站点内容历史记录

这就完了？不打算让博客内容管理更加自动化一些吗？比方说版本控制，自动部署等等。我们接下来就来介绍！

我们首先从使用Git管理站点内容历史记录开始说起。网站内容日新月异，因此有需要将我们的博客站点原始内容，如博客文章的原始Markdown文件，站点的配置文件，Node.js包依赖等，做一些历史备份。

还可以注意到，Hexo的站点文件，包括配置、文章等，实际上都可以被视为文本文件，因此Git就是负责管理版本历史的极佳选择。

以下方法不依赖于具体的Git云托管平台，因此不必纠结Github还是Gitee这种问题，原理都是一样的。

初始化Git仓库

进入Hexo主文件夹，并执行git init，这将在本地端创建一个初始Git仓库。

1
2

cd MyBlog
git init

接着，我们让git跟踪Hexo主文件夹内所有有用的文件，并进行第一次提交(commit)。其中-m参数后的是提交信息，内容任你填写。

1
2

git add .
git commit -m "Init commit."

推送到在线Git云托管平台

如果希望同步到在线的Git云托管平台，需要先自行在网页中创建一个空仓库，之后推送到该远程仓库中。这里以内网的一台Git服务器为例，创建的仓库地址为http://git.mysrv.in/dhao2001/MyBlog.git

1
2

git remote add origin http://git.mysrv.in/dhao2001/MyBlog.git
git push -u origin main

在另一个地方继续创作

下次，当重装了操作系统，或是更换了电脑，希望在另一个地方恢复相同的博客环境以及源文件，只需要这么做:

首先还是要搭好最基本的环境，也就是git, nodejs, npm。安装完成后克隆仓库到当前系统。

`1`	`git clone http://git.mysrv.in/dhao2001/MyBlog.git`

进入该文件夹，执行npm install，这将根据Hexo主文件夹里的package.json文件，安装所需的node.js包。

1
2

cd MyBlog
npm install

至此，在新环境中的博客编写环境已经准备就绪，就可以像在老地方一样创作和发布博客了。

(可选)使用Git进行页面部署

咦，怎么又是Git？上一节不是刚刚才讲过吗？

刚刚上一节的内容，主要是使用Git对博客的原始配置文件、原始代码、原始Markdown源文件进行管理。

而本节的内容是，使用Git工具，将本机上通过Hexo命令渲染生成的静态Html等站点资源文件，推送到远程服务器的指定Web目录内，供其他人通过Web服务器进行访问。

设置远程服务器

第一步，首先需要登录到博客网站主机，也就是部署在公网的Web服务器上。

接着，在服务器上安装git软件包。例如，如果使用的是Debian/Ubuntu系统，可以运行:

`1`	`sudo apt install git`

如果使用的是其他发行版，请参阅对应发行版的软件包安装手册。

设置Web服务器

📝 备注

关于Web服务器的选择

本教程以nginx作为Web服务器，若希望使用其他Web服务器如Apache，请自行调整以下步骤中Web服务器配置文件内容。

在/var/www下新建一个文件夹，用于存放博客网站的静态Html文件，这里以blog作为文件夹名称示例。

`1`	`mkdir -p /var/www/blog`

接下来修改nginx的站点配置文件(Debian/Ubuntu系统位于/etc/nginx/sites-enabled/下)，修改配置文件中的server块(当然，更建议新建一个server块，更方便区分和管理，详见其他教程)。

server {
        listen 80 default_server;
        listen [::]:80 default_server;

        root /var/www/blog;

        index index.html;

        server_name _;

        location / {
                try_files $uri $uri/ =404;
        }
}

修改完配置文件后，重启nginx:

service nginx restart   # 使用系统服务管理重启nginx

# 如果上面的命令无效
nginx -s reload         # 使用nginx命令重新读取配置文件

以上配置足以满足Hexo这样的静态网站部署要求。此时，可以考虑在/var/www/blog/下新建一个测试用Html文件，测试能否正常访问网站。

设置git仓库用于传输博客网站资源

设置好Web服务器后，如何使用git，把本机生成好的Hexo站点静态文件，推送到远程Web服务器上的网站目录，也就是本例中的/var/www/blog去呢？

实际上，在服务器和本地机器之间传输文件有很多方法。为了方便，考虑Hexo提供的部署工具集合，我们可以继续使用Git工具完成这项任务。

使用Git传输网站资源主要分成两个过程：

第一步，先将本机生成的静态文件，通过Git传输到Web服务器上。
第二步，使用Git钩子，将传输到Web服务器上的网站资源，复制到/var/www/blog，供Web用户访问。

为了达到这一目标，需要按照以下方法，在本机和远程Web服务器上分别调整配置。

远程Web服务器的配置

首先，在远程Web服务器上，创建一个用户，用户名可以自拟。当然，考虑使用Git的习惯，甚至可以给这个用户起名为git，如本例接下来所示。

`1`	`adduser -s /bin/git-shell git`

⚠️ 警告

关于Git Shell

出于安全考虑，可以将git用户的默认shell指定为只有简单功能的git-shell，执行命令结束后就会退出。

注意，/bin/git-shell是Debian/Ubuntu系发行版的默认路径，新版本或其他发行版请务必确认git-shell的具体位置，并将/bin/git-shell替换成真实路径。

为了配置自动部署，建议使用密钥对进行认证。SSH密钥对可以在本机上使用ssh-keygen或putty等工具生成。

sudo -u git /bin/bash -i        # 以git用户身份进行下列操作
cd ~
mkdir .ssh
cd .ssh
vim authorized_keys             # 将公钥添加到authorized_keys中
chmod 600 authorized_keys

完成用户创建后，选择任意一处地方，创建一个git裸仓库，该仓库就是用于传输网站资源的git仓库。如果没有其他要求的话，git用户的家目录/home/git似乎就是一个不错的选择。

1
2

cd ~
git init -b main --bare myblog.git

为了在上传网站资源文件后，git可以自动帮我们将更新的资源文件，拷贝到/var/www/blog文件夹，我们需要在git仓库中创建一个post-receive钩子。

`1`	`vim myblog.git/hooks/post-receive`

添加如下内容：

1
2

#!/bin/sh
git --work-tree=/var/www/blog --git-dir=/home/git/myblog.git checkout -f

保存该文件，回到终端，赋予该文件可执行权限。

`1`	`chmod 744 myblog.git/hooks/post-receive`

也不要忘记将nginx网站根目录/var/www/blog所有权转移给用户git，否则将无法进行写入和更新操作！

`1`	`chown -R git:git /var/www/blog`

这样，远程Web服务器端的配置就完成了。

本机端的操作

这部分的配置也可以参考官方文档One-Command Deployment | Hexo。

回到本机上的WSL Hexo环境。首先切到Hexo主文件夹。

`1`	`cd MyBlog`

为了使用Git进行一键部署，我们需要安装Hexo的Git一键部署插件。

`1`	`npm install hexo-deployer-git --save`

在_config.yml最后deploy下添加一节。

deploy:
  - type: git
    repo: git@mysrv.in:myblog.git
    branch: main
    message:

记得把mysrv.in替换成你的远程Web服务器地址。如果有其他需求，如指定认证使用的私钥位置、端口等，可以参考我先前写的文章SSH配置主机别名及指定认证私钥路径，修改ssh_config文件实现。

完成以后，试试运行命令:

`1`	`hexo g -d`

然后再访问一下博客站点，是不是已经成功将Hexo内容部署上去了呢？

常见问题的解决

本机部署命令执行成功，但远程服务器上访问到的资源未更新

在调试网站并刷新时，建议使用Ctrl+F5快捷键强制刷新，这将强制浏览器重新请求网站文件，从而可以避免缓存对调试结果造成影响。

其次，检查网站目录/var/www/blog的内容是否已经更新，以及nginx配置文件正确性。

如果明明git推送成功，但却没更新到网站目录中，需要检查post-receive钩子内容是否正确，路径是否正确，权限是否正确。

在这里，post-receive钩子文件对以上用户（本例中为git）必须具备可执行权限。同时，nginx的站点文件夹（本例中为/var/www/blog）必须对git用户开放写入权限，对nginx用户www-data开放读取权限。

正确的权限是，权限8进制代码为744或755，所有者为git:git。可以通过下列命令指定。

如果不确定，可以以git用户身份尝试以下命令：

1
2
3

cd ~
chown git:git myblog.git/hooks/post-receive
chmod 744 myblog.git/hooks/post-receive

再以root身份执行以下命令：

1
2

sudo chown -R git:git /var/www/blog
sudo chmod -R 744 /var/www/blog

修改博客后更新资源时，发现生成的页面字母大小写异常

这是由于默认的Hexo Git插件对大小写不敏感导致的。需要修改<Hexo主目录>/.deploy_git/.git/下面的config文件，在[core]一节中添加一行ignorecase = false:

[core]
        repositoryformatversion = 0
        filemode = true
        bare = false
        logallrefupdates = true
+       ignorecase = false
[branch "master"]
        remote = git@mysrv.in:myblog.git
        merge = refs/heads/master

为Powershell启用更舒服的自动补全

Mon, 06 Dec 2021 01:30:00 +0800

为什么要写这个呢？

主要吧，现在在Windows上，不管有什么多种多样的shell移植如Msys，Cygwin之类，用得最多最方便的，特别是和我目前主要使用的两个IDE/编辑器: Visual Studio与Visual Studio Code最相合的，肯定是Powershell。

但是，默认的Powershell自动补全非常难用，可以自动补全的参数就寥寥几个。我觉得还是可以稍微改进一下。

方法

首先需要安装好PSReadLine模块。

安装好后，使用你最喜欢的编辑器，编辑$PROFILE这个变量对应的文件。这里我们以使用Windows自带的记事本notepad为例，在Powershell中输入:

`1`	`notepad $PROFILE`

添加如下片段:

Import-Module PSReadLine

## Shows navigable menu of all options when hitting Tab
Set-PSReadLineKeyHandler -Key Tab -Function MenuComplete

## Autocompleteion for Arrow keys
Set-PSReadLineOption -HistorySearchCursorMovesToEnd
Set-PSReadLineKeyHandler -Key UpArrow -Function HistorySearchBackward
Set-PSReadLineKeyHandler -Key DownArrow -Function HistorySearchForward

Set-PSReadLineOption -ShowToolTips
Set-PSReadLineOption -PredictionSource History

#Set the color for Prediction (auto-suggestion)
Set-PSReadLineOption -Colors @{
  Command            = 'Magenta'
  Number             = 'DarkBlue'
  Member             = 'DarkBlue'
  Operator           = 'DarkBlue'
  Type               = 'DarkBlue'
  Variable           = 'DarkGreen'
  Parameter          = 'DarkGreen'
  ContinuationPrompt = 'DarkBlue'
  Default            = 'DarkBlue'
  InlinePrediction   = 'DarkGray'
}

oh-my-posh --init --shell pwsh --config ~/jandedobbeleer.omp.json | Invoke-Expression

每句配置的含义都非常容易懂。颜色部分是我自己定义的，都可以自由改动。此外我还使用了oh-my-posh定义shell的样式。改动结束后，保存文件，重新打开Powershell即可应用配置。或者使用. $PROFILE以在当前终端读取配置文件。

使用VSCode编写Latex文章

Mon, 06 Dec 2021 01:27:24 +0800

因此从易用性角度还是选用了VSCode，一开始以为配置VSCode使用LaTeX会非常麻烦，但实际上比想象中简单很多。

预备条件

VSCode
VSCode插件LaTeX Workshop
Tex环境套件，更推荐TeXLive

TeXLive套件可以从TUG网站上下载安装，如果用的是Linux也可以直接使用系统软件源中提供的打包，功能上都是等价的。

如果文章是中文的，需要在定制功能的时候选择中文的支持和字体，并最好安装XeTeX组件，该组件支持Unicode文件编码，对中文的处理更好。

📝 备注

latexindent报错问题

latexindent是格式化.tex文件的常见选择。然而如果在Debian/Ubuntu上运行该程序时出现了类似以下报错：Can't locate Config/YAML.pm in @INC或是Can't locate File/HomeDir.pm in @INC，这表明当前系统中的perl没有安装相应的模块。

在Debian/Ubuntu下，与其费劲从CPAN安装，不如直接apt install libyaml-tiny-perl libfile-homedir-perl，几秒钟搞定。

配置工作区

配置文件其实是参考的https://zhuanlan.zhihu.com/p/38178015

不过，我更喜欢将设置放到工作区里面，这样就更方便一些。

丢上我的配置文件.vscode/settings.json

{
    "latex-workshop.latex.tools": [
        {
            "name": "xelatex",
            "command": "xelatex",
            "args": [
                "-synctex=1",
                "-interaction=nonstopmode",
                "-file-line-error",
                "-pdf",
                "%DOCFILE%"
            ]
        },
        {
            "name": "pdflatex",
            "command": "pdflatex",
            "args": [
                "-synctex=1",
                "-interaction=nonstopmode",
                "-file-line-error",
                "%DOCFILE%"
            ]
        },
        {
            "name": "bibtex",
            "command": "bibtex",
            "args": [
                "%DOCFILE%"
            ]
        }
    ],
    "latex-workshop.latex.recipes": [
        {
            "name": "xelatex",
            "tools": [
                "xelatex"
            ],
        },
        {
            "name": "pdflatex",
            "tools": [
                "pdflatex"
            ]
        },
        {
            "name": "xe->bib->xe->xe",
            "tools": [
                "xelatex",
                "bibtex",
                "xelatex",
                "xelatex"
            ]
        },
        {
            "name": "pdf->bib->pdf->pdf",
            "tools": [
                "pdflatex",
                "bibtex",
                "pdflatex",
                "pdflatex"
            ]
        }
    ],
    "latex-workshop.view.pdf.viewer": "browser"
}

注意，我这里设置了在默认浏览器中预览生成的PDF，这是因为我有两个屏幕，一个编写一个预览，如果你觉得集成在一个VSCode窗口里更好，请把browser换成tab。

编译的时候，只需要在VSCode左侧，TeX，点xetex旁边的播放按钮，就会启动编译流程。