Windows 和 WSL 设置

Meridian 从类 Unix 终端运行。在 Windows 上，请使用 Windows Subsystem for Linux (WSL)，并在 Linux 环境中运行 Meridian。

原生 PowerShell、Command Prompt、Git Bash 和 Cygwin 不是 Meridian 的推荐路径。WSL 提供与 Linux 相同的 shell、SSH 和文件系统行为，与其余文档保持一致。

安装 WSL

以管理员身份打开 PowerShell 并安装 WSL：

wsl --install

如果系统提示，请重启，然后从 Start 菜单打开已安装的 Linux 发行版。

Ubuntu 是最安全的默认选择，因为 Meridian 面向 Debian 和 Ubuntu 服务器，并且大多数示例使用 apt 包名。如果您已经在 WSL 中安装了 Debian，也可以使用。

检查 WSL 是否使用版本 2：

wsl --list --verbose

如果您的发行版显示版本 1，请转换它：

wsl --set-version Ubuntu 2

在 WSL 终端中，更新包并安装基础工具：

sudo apt update
sudo apt install -y curl openssh-client ca-certificates

安装 Meridian：

curl -sSf https://getmeridian.org/install.sh | bash

如果 meridian 没有立即找到，请重启 WSL 终端或重新加载 shell profile：

exec "$SHELL" -l

验证安装：

meridian --version

Meridian 从 WSL 通过 SSH 连接到您的 VPS。请在 WSL 内生成密钥：

ssh-keygen -t ed25519 -C "meridian-wsl"

复制公钥：

cat ~/.ssh/id_ed25519.pub

将该公钥添加到 VPS 提供商，或添加到服务器用户的 ~/.ssh/authorized_keys。

运行 Meridian 前先测试 SSH：

ssh root@198.51.100.10

如果您的 VPS 使用非 root 用户，请测试该用户并传给 deploy：

meridian deploy 198.51.100.10 --user ubuntu

如果密钥有 passphrase，请在 WSL 内启动 agent：

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

只有在理解安全取舍时，才把这些命令加入 ~/.profile 或 ~/.bashrc。对于大多数首次部署，手动启动 agent 就够了。

刚开始时避免混用 Windows 和 WSL 的 SSH agent。先把密钥和 agent 都放在 WSL 内，直到部署正常工作。

从 WSL 终端运行正常部署流程：

meridian deploy

或者直接提供服务器 IP：

meridian deploy 198.51.100.10

Meridian 会把凭据保存在 WSL 内的 ~/.config/meridian/。后续命令也从同一个 WSL 发行版运行，这样它才能找到缓存的服务器凭据：

meridian client add alice
meridian client list
meridian test 198.51.100.10

如果使用 VS Code，请安装 “WSL” 扩展，并从 WSL 打开 Meridian 工作区：

code .

通过 Remote WSL 编辑的文件位于 Linux 文件系统中，可避免路径和权限问题。优先使用 WSL home 下的路径，例如 ~/projects，不要通过 /mnt/c/ 编辑 Meridian 状态或 SSH 密钥。

某些交互式终端提示在 WSL 下可能表现不同。如果 deploy 向导没有按预期接受输入，请显式提供值：

meridian deploy 198.51.100.10 --sni www.cloudflare.com

也可以先检查服务器：

meridian check 198.51.100.10

确认密钥存在于 WSL 中，而不仅是在 Windows 中：

ls -la ~/.ssh
ssh -v root@198.51.100.10

私钥应只允许您的 WSL 用户读取：

chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519

重新加载 shell：

exec "$SHELL" -l

如果仍然找不到，请检查常见的 uv 和本地二进制路径：

ls ~/.local/bin

如有需要，把 ~/.local/bin 添加到 shell profile：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
exec "$SHELL" -l

将 SSH 密钥、Meridian 凭据和项目文件保存在 WSL 文件系统中：

cd ~
mkdir -p projects

避免把 ~/.ssh 或 ~/.config/meridian 放在 /mnt/c/ 下。Windows 挂载路径可能有不同的权限，SSH 会拒绝它们。