在一期部署中，我们成功搭建了基于 SystemdSpawner 与本地 PAM 认证的多用户 JupyterHub。随着团队规模的扩大，手动管理 Linux 用户、维护密码不仅繁琐，而且无法满足企业对单点登录（SSO）与多因素认证（MFA）的安全合规要求。

本期我们将 JupyterHub 升级为 Azure AD（Microsoft Entra ID）OAuth2 认证。由于一期已经严格遵循了统一的用户名规范，本次升级无需迁移已有用户数据，可以实现无痛过渡。

二期架构与认证时序

2.1 网络架构

在二期架构中，为支持 OAuth2 回调，引入了应用负载均衡器（ALB）并配置公网域名：

内网用户
  │
  ▼
http://jupyter.x.com  （内网 DNS，HTTP，80）
  │  内网 DNS 解析到 JupyterHub 实例内网 IP
  ▼
JupyterHub 实例
  │
  ▼  OAuth 认证跳转与回调
https://jupyter-callback.x.com  （公网 ALB，HTTPS，443）
  │  ALB 负责终止 TLS 并转发流量
  ▼
JupyterHub 服务（0.0.0.0:8000）
  │
  ├─ 认证：Azure AD OAuth2（用户生命周期完全托管于 Azure 侧）
  │
  └─ Spawner：SystemdSpawner
     └─ 用户首次登录 → 自动创建 Linux 系统用户 → 独立 Systemd 实例

2.2 认证时序

1. 用户访问 http://jupyter.x.com
         │
2. JupyterHub 发起 302 重定向到 Azure AD 登录页面
         │  带上参数 redirect_uri=https://jupyter-callback.x.com/hub/oauth_callback
         │
3. 用户在 Azure AD 侧进行身份验证（如 MFA 校验）
         │
4. Azure AD 认证通过，重定向回公网回调地址：
         │  https://jupyter-callback.x.com/hub/oauth_callback?code=xxx
         │
5. JupyterHub 收到回调请求，通过 ALB 转发至本地服务
         │
6. JupyterHub 用 code 换取 token 并提取用户邮箱 (upn claim)
         │
7. 触发 normalize_username 处理：例如 zhang.san@x.com 规范化为 zhang-san
         │
8. 触发 pre_spawn_hook 钩子：
         │  - 自动创建 Linux 用户 zhang-san （如果一期已存在则直接复用）
         │  - 自动初始化工作目录并设为 700 权限
         │  - 自动为新用户构建 Conda 环境与 Kernel 注册
         │
9. 启动对应的 systemd 实例 jupyter-zhang-san.service，引导用户进入 JupyterLab

Azure AD 应用注册

在配置 JupyterHub 之前，需要登录 Azure Portal 注册企业应用。

1. 注册应用

1. 打开 Azure Portal，依次进入 Microsoft Entra ID (原 Azure Active Directory) -> 应用注册 -> 新注册。
2. 填写注册信息：
   • 名称：JupyterHub
   • 受支持的账户类型：根据租户范围选择（通常选择单租户）。
   • 重定向 URI：平台选择 Web，值填写 https://jupyter-callback.x.com/hub/oauth_callback。

2. 获取必要凭证

在应用概述页和凭证页，记录以下关键信息用于 JupyterHub 配置：

• 目录（租户）ID (tenant_id)：xxxx
• 应用程序（客户端）ID (client_id)：xxxx
• 客户端密码 (client_secret)：在“证书和密码”页，新建客户端密码，并立即复制记录其 Value（注意不是密码 ID）。

3. 配置 API 权限

在“API 权限”中，添加以下 Microsoft Graph 委托权限：

• openid
• email
• profile
• User.Read

添加完成后，务必点击“代表 [您的组织] 授予管理员同意”。

环境依赖更新

由于增加了 OAuth2 认证支持，需要在已有的 JupyterHub 虚拟环境中追加安装 oauthenticator 库：

conda activate jupyterhub
pip install oauthenticator

完整 JupyterHub 配置

修改 /etc/jupyterhub/jupyterhub_config.py，配置 Azure AD 认证器，并实现自动创建 Linux 用户与环境的完整版钩子函数。

import os
import pwd
import grp
import re
import subprocess

c = get_config()  #noqa

# ═══════════════════════════════════════════════════════
# 全局变量
# ═══════════════════════════════════════════════════════
JUPYTER_USER_DIR = '/data/jupyter-users'
JUPYTER_GROUP = 'jupyterhub-users'

# ═══════════════════════════════════════════════════════
# 网络配置
# ═══════════════════════════════════════════════════════
c.JupyterHub.ip = '0.0.0.0'
c.JupyterHub.port = 8000
c.JupyterHub.base_url = '/'

# CRYPT_KEY：使用 openssl rand -hex 32 生成
os.environ.setdefault('JUPYTERHUB_CRYPT_KEY', 'xxxx')

# ═══════════════════════════════════════════════════════
# Azure AD OAuth 认证与用户名规范化
# ═══════════════════════════════════════════════════════
from oauthenticator.azuread import AzureAdOAuthenticator

class NormalizedAzureAdOAuthenticator(AzureAdOAuthenticator):
    """
    覆写 normalize_username，确保 Azure AD 传回的邮箱格式能够无缝转换为合法的 Linux 用户名。
    转换示例：zhang.san@x.com → zhang-san
    """
    def normalize_username(self, username):
        # 取 @ 前面的邮箱前缀
        name = username.split('@')[0]
        # 将点、下划线、空格等统一转换为短横线，并转为小写
        name = name.replace('.', '-').replace('_', '-').replace(' ', '-').lower()
        # 移除非法字符，限制仅能包含小写字母、数字和短横线
        name = re.sub(r'[^a-z0-9-]', '', name)
        # 截断长度（Linux 用户名限制最长 32 字符）
        name = name[:32]
        return super().normalize_username(name)

c.JupyterHub.authenticator_class = NormalizedAzureAdOAuthenticator

# Azure AD 凭证配置
c.AzureAdOAuthenticator.tenant_id = 'xxxx'
c.AzureAdOAuthenticator.client_id = 'xxxx'
c.AzureAdOAuthenticator.client_secret = 'xxxx'
c.AzureAdOAuthenticator.oauth_callback_url = 'https://jupyter-callback.x.com/hub/oauth_callback'

# 关键：指定 username_claim 为 upn（用户主体名），确保获取到合法的邮箱格式
c.AzureAdOAuthenticator.username_claim = 'upn'

# 允许所有通过当前 Azure AD 租户认证的用户登录
c.AzureAdOAuthenticator.allow_all = True

# 管理员用户配置（配置为规范化后的 Linux 用户名）
c.Authenticator.admin_users = {'admin'}

# ═══════════════════════════════════════════════════════
# SystemdSpawner 配置
# ═══════════════════════════════════════════════════════
c.JupyterHub.spawner_class = 'systemdspawner.SystemdSpawner'
c.Spawner.default_url = '/lab'
c.SystemdSpawner.unit_name_template = 'jupyter-{USERNAME}'
c.Spawner.notebook_dir = JUPYTER_USER_DIR + '/{username}'
c.SystemdSpawner.default_shell = '/bin/bash'
c.SystemdSpawner.isolate_tmp = True
c.SystemdSpawner.isolate_devices = True
c.SystemdSpawner.disable_user_sudo = True
c.SystemdSpawner.slice = 'jupyter-users.slice'

# ═══════════════════════════════════════════════════════
# 自动化用户供给：pre_spawn_hook
# ═══════════════════════════════════════════════════════
CONDA_BIN = '/opt/miniconda3/bin/conda'
USERADD_BIN = '/usr/sbin/useradd'
GROUPADD_BIN = '/usr/sbin/groupadd'

def ensure_system_user(spawner):
    """
    当用户首次通过 Azure AD 登录时，自动执行以下供给逻辑：
    1. 创建 JupyterHub 共享用户组
    2. 创建对应的 Linux 系统用户（禁止 SSH 登录但允许 Terminal 内执行 cron）
    3. 自动初始化 700 隔离工作目录
    4. 写入 Conda 环境变量至其 .bashrc
    5. 构建专属 Conda 隔离沙箱并注册 Jupyter 内核
    """
    username = spawner.user.name

    # 严格校验：确保用户名必须符合规范化正则，拒绝非法输入直接写入系统命令
    if not re.fullmatch(r'[a-z0-9-]{1,32}', username):
        raise ValueError(
            f'Refusing to spawn: username {username!r} is not normalized. '
            f'请检查配置的 username_claim 或清理 jupyterhub.sqlite 中的脏数据。'
        )

    user_dir = f'{JUPYTER_USER_DIR}/{username}'
    conda_env_prefix = f'{user_dir}/.conda/envs/{username}'

    # 1. 确保 jupyterhub-users 组存在
    try:
        grp.getgrnam(JUPYTER_GROUP)
    except KeyError:
        subprocess.run([GROUPADD_BIN, JUPYTER_GROUP], check=True)

    # 2. 如果用户不存在则创建 Linux 用户
    is_new_user = False
    try:
        pwd.getpwnam(username)
    except KeyError:
        subprocess.run([
            USERADD_BIN,
            '-m',
            '-d', user_dir,
            '-s', '/bin/bash',
            '-g', JUPYTER_GROUP,
            '-G', 'crontab',
            '--no-user-group',
            username
        ], check=True)
        spawner.log.info(f'Created system user: {username}')
        is_new_user = True

    # 3. 确保目录存在并强制设定权限
    os.makedirs(user_dir, exist_ok=True)
    user_info = pwd.getpwnam(username)
    os.chown(user_dir, user_info.pw_uid, user_info.pw_gid)
    os.chmod(user_dir, 0o700)

    # 4. 配置 .bashrc 中的 Conda PATH
    if is_new_user:
        bashrc = f'{user_dir}/.bashrc'
        with open(bashrc, 'a') as f:
            f.write('\nexport PATH="/opt/miniconda3/bin:$PATH"\n')
        os.chown(bashrc, user_info.pw_uid, user_info.pw_gid)

    # 5. 构建专属 Conda 沙箱及注册内核（仅在新环境未被初始化时执行）
    if not os.path.exists(conda_env_prefix):
        spawner.log.info(f'Creating conda env: {conda_env_prefix}')
        subprocess.run([
            CONDA_BIN, 'create', '-y',
            '-c', 'conda-forge', '--override-channels',
            '--prefix', conda_env_prefix,
            'python=3.12'
        ], check=True)
        
        subprocess.run([
            CONDA_BIN, 'run', '--prefix', conda_env_prefix,
            'pip', 'install', 'ipykernel'
        ], check=True)

        kernel_prefix = f'{user_dir}/.local'
        subprocess.run([
            CONDA_BIN, 'run', '--prefix', conda_env_prefix,
            'python', '-m', 'ipykernel', 'install',
            '--prefix', kernel_prefix,
            '--name', username,
            '--display-name', f'Python ({username})'
        ], check=True)

        # 递归修正 conda 和 kernel specs 目录权限，以防以 root 身份创建时发生权限溢出
        conda_dir = f'{user_dir}/.conda'
        for root, dirs, files in os.walk(conda_dir):
            for d in dirs:
                os.chown(os.path.join(root, d), user_info.pw_uid, user_info.pw_gid)
            for f in files:
                os.chown(os.path.join(root, f), user_info.pw_uid, user_info.pw_gid)
        os.chown(conda_dir, user_info.pw_uid, user_info.pw_gid)

        for root, dirs, files in os.walk(kernel_prefix):
            for d in dirs:
                os.chown(os.path.join(root, d), user_info.pw_uid, user_info.pw_gid)
            for f in files:
                os.chown(os.path.join(root, f), user_info.pw_uid, user_info.pw_gid)
        os.chown(kernel_prefix, user_info.pw_uid, user_info.pw_gid)
        spawner.log.info(f'Conda env and kernel ready for user: {username}')

    spawner.log.info(f'User environment setup completed: {user_dir}')

c.Spawner.pre_spawn_hook = ensure_system_user

# ═══════════════════════════════════════════════════════
# 反向代理集成与 Cookie 域配置
# ═══════════════════════════════════════════════════════
c.JupyterHub.tornado_settings = {
    'cookie_options': {'domain': '.x.com'},
    'headers': {
        'Content-Security-Policy': "frame-ancestors 'self'"
    }
}

负载均衡器（ALB）配置要点

为了保证 OAuth2 的回调安全及 WebSocket 长连接的连贯性，ALB 侧的配置应遵循以下指标：

用户生命周期管理策略对照

在两种架构下，系统管理员对用户的生命周期管理操作如下：

共享只读数据目录（可选拓展）

如果团队内有公共数据集或共享代码包，需要提供给所有用户只读挂载：

1. 在宿主机创建共享目录并赋权：

   sudo mkdir -p /data/jupyter-shared
   sudo chown root:jupyterhub-users /data/jupyter-shared
   sudo chmod 750 /data/jupyter-shared
   

2. 在 ensure_system_user 函数末尾追加软链接建立逻辑：

   # 在 pre_spawn_hook 钩子函数的最后加入：
   shared_link = os.path.join(user_dir, 'shared-data')
   if not os.path.exists(shared_link):
       os.symlink('/data/jupyter-shared', shared_link)
   

这样，每个用户在登录 JupyterLab 后，工作目录下都会自动出现一个名为 shared-data 的软链接，从而实现数据零拷贝的高效共享。

多用户 Jupyter 平台常见方案是基于 Kubernetes (Zero to JupyterHub) 或 Docker (DockerSpawner)。但对于中小团队或单机部署，Kubernetes 维护成本过高，DockerSpawner 存在数据权限映射和容器管理开销。

我们需要一个更轻量、贴合宿主机环境的方案。SystemdSpawner 是一个理想的选择：它能够利用 Linux 原生 systemd 服务的 cgroup 限制 CPU 和内存资源，且用户打开 Terminal 直接就是真实的宿主机 Shell，方便使用宿主机已安装的各种开发工具。这非常适合单机、多用户的高效共享开发服务器。

分期部署策略

为了平稳上线，部署工作分两期进行：

无痛迁移的前提：第一期创建用户时，命名规则必须与第二期 normalize_username 函数输出一致（即邮箱 @ 前部分，. 和 _ 替换为 -，全小写）。例如 zhang.san@x.com → zhang-san。

这样在切换认证方式时，已有的 Linux 用户和 /data/jupyter-users/{username} 目录无需进行任何迁移，已有的用户数据可以完全保留。

一期架构概览

一期采用纯内网运行方式，架构如下：

内网用户
  │
  ▼
http://jupyter.x.com  （内网 DNS，HTTP，80）
  │  内网 DNS 解析到内网 IP
  ▼
JupyterHub（0.0.0.0:8000）
  │
  ├─ 认证：PAM（Linux 系统用户密码）
  │
  └─ Spawner：SystemdSpawner
     └─ 每个用户 → 独立 systemd unit → cgroup 隔离
        └─ 工作目录 /data/jupyter-users/{username}（权限 700，互不可见）

命名规范

为确保第二期无缝切换，第一期创建用户时严格遵循以下规则：

1. 取邮箱 @ 前面的部分。
2. . 替换为 -。
3. _ 替换为 -。
4. 全部小写。
5. 最长 32 字符。

示例：

系统依赖安装

首先在 Ubuntu 服务器上安装基础依赖，并为 JupyterHub 构建独立的 Python 虚拟环境。

# 基础依赖安装
sudo apt update && sudo apt install -y python3-pip python3-venv nodejs npm acl

# 创建虚拟环境（指定 conda-forge 源，避免 Anaconda 官方 ToS 拦截）
conda create -y -c conda-forge --override-channels --prefix /data/condaenv/jupyterhub python=3.13
conda activate jupyterhub 

# 安装 JupyterHub 和 SystemdSpawner
pip install jupyterhub jupyterlab jupyterhub-systemdspawner

# 安装代理组件
sudo npm install -g configurable-http-proxy

# 创建数据根目录
sudo mkdir -p /data/jupyter-users
sudo chmod 755 /data/jupyter-users

第一期配置文件

创建配置文件目录并写入 /etc/jupyterhub/jupyterhub_config.py。

一期配置文件中，主要使用本地 PAMAuthenticator，并在 pre_spawn_hook 中修正手动创建的用户的目录权限。

import os
import pwd
import grp
import subprocess

c = get_config()  #noqa

# ═══════════════════════════════════════════════════════
# 全局变量
# ═══════════════════════════════════════════════════════
JUPYTER_USER_DIR = '/data/jupyter-users'
JUPYTER_GROUP = 'jupyterhub-users'

# ═══════════════════════════════════════════════════════
# 网络配置
# ═══════════════════════════════════════════════════════
c.JupyterHub.ip = '0.0.0.0'
c.JupyterHub.port = 8000
c.JupyterHub.base_url = '/'

# CRYPT_KEY：使用 openssl rand -hex 32 生成
os.environ.setdefault('JUPYTERHUB_CRYPT_KEY', 'xxxx')

# ═══════════════════════════════════════════════════════
# 第一期：PAM 本地认证
# ═══════════════════════════════════════════════════════
c.JupyterHub.authenticator_class = 'jupyterhub.auth.PAMAuthenticator'

# 管理员与允许登录的用户列表
c.Authenticator.admin_users = {'admin'}
c.Authenticator.allowed_users = {'admin'}

# ═══════════════════════════════════════════════════════
# SystemdSpawner 配置
# ═══════════════════════════════════════════════════════
c.JupyterHub.spawner_class = 'systemdspawner.SystemdSpawner'
c.Spawner.default_url = '/lab'
c.SystemdSpawner.unit_name_template = 'jupyter-{USERNAME}'
c.Spawner.notebook_dir = JUPYTER_USER_DIR + '/{username}'
c.SystemdSpawner.default_shell = '/bin/bash'
c.SystemdSpawner.isolate_tmp = True
c.SystemdSpawner.isolate_devices = True
c.SystemdSpawner.disable_user_sudo = True

# ═══════════════════════════════════════════════════════
# pre_spawn_hook（确保目录存在并赋权，一期用户已手动创建）
# ═══════════════════════════════════════════════════════
def ensure_system_user(spawner):
    username = spawner.user.name
    user_dir = f'{JUPYTER_USER_DIR}/{username}'
    os.makedirs(user_dir, exist_ok=True)
    user_info = pwd.getpwnam(username)
    os.chown(user_dir, user_info.pw_uid, user_info.pw_gid)
    os.chmod(user_dir, 0o700)

c.Spawner.pre_spawn_hook = ensure_system_user

用户管理与环境初始化

一期需要手动在 Linux 宿主机上创建用户，并限制其登录权限，同时为其初始化专属的 Conda 环境和内核。

# 创建用户组（一次性）
sudo groupadd jupyterhub-users

# 禁止 jupyterhub-users 组通过 SSH 登录
echo 'DenyGroups jupyterhub-users' | sudo tee -a /etc/ssh/sshd_config
sudo systemctl reload ssh

# 新增用户（用户名按命名规范命名）
USERNAME=admin
# 使用 -m 选项自动创建目录并拷贝 /etc/skel 默认配置
sudo useradd -m -d /data/jupyter-users/${USERNAME} -s /bin/bash -g jupyterhub-users -G crontab --no-user-group ${USERNAME}
sudo passwd ${USERNAME}

# 修正权限，保证目录仅限用户本人访问
sudo chmod 700 /data/jupyter-users/${USERNAME}

# 写入 conda PATH，使用户 Terminal 能直接使用 conda 命令
echo 'export PATH="/opt/miniconda3/bin:$PATH"' | sudo tee -a /data/jupyter-users/${USERNAME}/.bashrc

# 创建与用户名同名的 conda 环境，并注册为 Jupyter kernel
sudo -u ${USERNAME} /opt/miniconda3/bin/conda create -y -c conda-forge --override-channels --prefix /data/jupyter-users/${USERNAME}/.conda/envs/${USERNAME} python=3.12
sudo -u ${USERNAME} /opt/miniconda3/bin/conda run --prefix /data/jupyter-users/${USERNAME}/.conda/envs/${USERNAME} \
    pip install ipykernel
sudo -u ${USERNAME} /opt/miniconda3/bin/conda run --prefix /data/jupyter-users/${USERNAME}/.conda/envs/${USERNAME} \
    python -m ipykernel install --user --name ${USERNAME} --display-name "Python (${USERNAME})"

# 修正 .conda 目录的所属用户和组
sudo chown -R ${USERNAME}:jupyterhub-users /data/jupyter-users/${USERNAME}/.conda

注意：每当手动新增用户后，必须在 jupyterhub_config.py 的 allowed_users 中添加对应用户名，然后重启 JupyterHub。

Systemd 服务与资源限制

5.1 JupyterHub Systemd 配置

创建 /etc/systemd/system/jupyterhub.service：

[Unit]
Description=JupyterHub
After=network.target

[Service]
# SystemdSpawner 需要 root 权限来管理用户级 systemd unit
User=root
# 必须包含 /usr/sbin，确保 subprocess 能够找到 useradd / groupadd 命令
Environment=PATH=/data/condaenv/jupyterhub/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
ExecStart=/data/condaenv/jupyterhub/bin/jupyterhub -f /etc/jupyterhub/jupyterhub_config.py
WorkingDirectory=/etc/jupyterhub
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

启动并使能服务：

sudo systemctl daemon-reload
sudo systemctl enable --now jupyterhub

5.2 资源限制（systemd slice）

为防止单用户资源超载导致整机崩溃，需要将所有用户进程归入 jupyter-users.slice 中进行统一限制。

创建 /etc/systemd/system/jupyter-users.slice：

[Slice]
Description=Resource limits for all JupyterHub user notebooks
# 示例：以 8核 32G 机器为例，限制用户总体 CPU 792%，内存最大 31G，达到 26G 开始触发软限制回收
CPUQuota=792%
MemoryMax=31G
MemoryHigh=26G

为了适应机器规格的自动调整，推荐使用动态配置脚本 /usr/local/bin/set-jupyter-limits.sh：

#!/bin/bash
set -e

CPU_CORES=$(nproc)
MEM_TOTAL=$(awk '/MemTotal/ {printf "%.0f", $2/1024/1024}' /proc/meminfo)

# 留出 1% 给系统和 JupyterHub 自身
CPU_LIMIT=$((CPU_CORES * 99))
MEM_LIMIT=$((MEM_TOTAL * 99 / 100))
MEM_HIGH=$((MEM_LIMIT * 85 / 100))

mkdir -p /etc/systemd/system/jupyter-users.slice.d/
cat > /etc/systemd/system/jupyter-users.slice.d/resource-limit.conf << CONF
[Slice]
CPUQuota=${CPU_LIMIT}%
MemoryMax=${MEM_LIMIT}G
MemoryHigh=${MEM_HIGH}G
CONF

systemctl daemon-reload
echo "Jupyter user limits set: CPU=${CPU_LIMIT}%, MemMax=${MEM_LIMIT}G, MemHigh=${MEM_HIGH}G"

赋予执行权限并创建开机自启服务：

sudo chmod +x /usr/local/bin/set-jupyter-limits.sh
sudo /usr/local/bin/set-jupyter-limits.sh

# 创建开机自启动 oneshot 服务
sudo tee /etc/systemd/system/jupyter-resource-limits.service << 'EOF'
[Unit]
Description=Dynamic Jupyter user resource limits
Before=jupyterhub.service

[Service]
Type=oneshot
ExecStart=/usr/local/bin/set-jupyter-limits.sh

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable jupyter-resource-limits.service

数据隔离验证

部署完毕后，登录不同的账户以验证多用户隔离效果：

1. 检查目录权限：

   ls -la /data/jupyter-users/
   # 应显示：
   # drwx------  zhang-san jupyterhub-users  zhang-san/
   # drwx------  li-si     jupyterhub-users  li-si/
   

2. 跨目录访问拦截：
   使用 zhang-san 身份尝试访问 li-si 的目录应被系统拦截：

   sudo -u zhang-san ls /data/jupyter-users/li-si/
   # 预期输出：ls: cannot open directory '/data/jupyter-users/li-si/': Permission denied
   

3. Jupyter Terminal 内测试：
   在 JupyterLab 中打开 Terminal 执行 ls /data/jupyter-users/，能够看到目录名称，但尝试读取任何其他用户文件都将返回 Permission denied。

随着企业业务的分布式发展和远程办公的普及，构建一个安全、高效且易于管理的内网变得至关重要。传统的 VPN 解决方案（如 OpenVPN、IPsec）配置繁琐，对客户端支持有限，且由于中心化架构容易产生网络瓶颈。

我们需要一个现代化的替代方案，它应该具备以下特质：部署简单、配置下发自动化、基于点对点直连（降低延迟），且拥有直观的管理面板。这就是我们选择 NetBird 的原因。它不仅满足上述所有需求，还完美地平衡了企业级安全需求与极简的运维体验。

NetBird 介绍

NetBird 是一个开源的现代零信任私有网络管理平台。它基于 WireGuard 协议构建，通过创建点对点（P2P）Mesh 网络，让位于不同地理位置、不同网络环境中的设备能够像身处同一个局域网内一样安全通信。

它包含四个核心组件：

• Management Service (管理服务)：集中控制平面，负责设备注册、认证、IP分配和访问控制规则的分发。
• Client Application (客户端)：安装在各终端节点上的代理程序，负责生成密钥并与其它节点建立 WireGuard 隧道。
• Signal Service (信令服务)：帮助处于 NAT 后的节点互相发现并协商直连通道（类似 WebRTC）。
• Relay Service (中继服务)：当节点间无法直接打洞穿透 NAT 时，作为备用方案进行流量转发（基于 WebSocket 或 TURN）。

NetBird 网络架构

NetBird 的架构设计精简而高效。一旦设备通过管理节点认证并获取了网络状态信息，设备之间就会尽可能建立点对点的 WireGuard 加密隧道，流量无需经过中心节点转发，极大提升了网络性能。

NetBird 特点

安全性，基于 WireGuard

NetBird 底层使用 WireGuard 协议进行数据传输。WireGuard 相比传统协议代码更少、更现代，且原生提供最先进的密码学加密机制。客户端在本地生成私钥，仅向管理服务上传公钥，确保任何第三方（甚至包括管理服务本身）都无法解密点对点传输的数据。

易用性，贴心的 Web 管理后台

与传统基于命令行或复杂配置文件的方案不同，NetBird 提供了一个现代、直观的 Web 控制台（Control Center）。管理员可以在可视化的界面中管理所有节点（Peers）、配置访问控制策略（ACL）、管理团队成员并配置 SSO 单点登录，极大降低了运维复杂度。

支持路由指定和下发，无须客户端配置

NetBird 允许在 Web 后台配置网络路由（Network Routes）。你可以指定某一个节点作为特定子网的出口网关，配置完成后，这些路由规则会自动下发到所有相关客户端。客户端无需进行任何手动干预或命令行操作，即可无缝访问指定的企业内部资源。

图形化客户端，对非技术人员友好

除了后端的易用性，NetBird 还为各大主流操作系统（Windows, macOS, 移动端等）提供了界面简洁的图形化客户端软件。对于团队中不具备网络配置经验的非技术人员（如设计、财务、产品经理），只需登录账号即可一键接入内网，完全没有使用门槛。

对比其他解决方案

在做技术选型时，我们将 NetBird 与其他主流组网方案进行了对比：

总结：对于需要完全开源、数据私有化部署且追求极致易用性的企业来说，NetBird 是目前的最佳选择。

NetBird 服务端安装过程

NetBird 服务端（即管理后台、信令服务等控制面组件）的自托管部署非常迅速，官方提供了一键安装脚本。

基础设施要求：

• 一台具有公网 IP 的 Linux 服务器（至少 1核 2GB 内存）。
• 服务器放行 TCP 80, 443 端口，以及 UDP 3478 端口。
• 准备一个解析到该服务器 IP 的公网域名（如 netbird.example.com 和 *.netbird.example.com）。
• 已安装 Docker 及其 Compose 插件，以及 jq 和 curl 工具。

详细安装步骤：

第一步：域名解析与环境准备
在开始前，请登录你的域名服务商控制台，添加两条 A 记录指向你的服务器 IP：

• @ 或 netbird 指向服务器 IP（用于管理后台）。
• * 或 *.netbird 指向服务器 IP（如果开启 Proxy 或需要泛域名证书）。
  确保服务器已安装 Docker (含 docker-compose) 以及 curl、jq。

第二步：执行安装脚本
在服务器终端执行官方的快速安装脚本：

curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh | bash

第三步：配置反向代理（自动化处理）
脚本运行后，会弹出一个交互式提示，询问你使用哪种反向代理：

Which reverse proxy will you use?
[0] Traefik (recommended)
[1] Existing Traefik ...

直接按回车选择默认的 [0] Traefik。它会在 Docker 里为你搞定一切，并自动通过 Let’s Encrypt 申请和续期 HTTPS 证书。

第四步：配置安全与代理组件
紧接着，脚本会询问是否开启 NetBird Proxy 服务（允许你把内网服务安全地暴露到公网），输入 y 开启。
如果开启了 Proxy，还会询问是否启用 CrowdSec（自动拦截恶意 IP 和网络攻击），建议一并开启以提升安全性。

第五步：初始化系统与账号
安装完成并且所有 Docker 容器成功启动后，打开浏览器访问你的域名：https://netbird.example.com。
系统检测到是初次部署，会自动跳转到 /setup 页面。在这里：

1. 输入你的邮箱和名字。
2. 设置你的管理员密码。
3. 点击创建账号。

完成账号创建后，你就会进入全新的 NetBird Web 控制台。至此，管理端搭建完毕，你可以下载客户端软件，开始添加你的第一台企业内网设备了！

第六步：进程常驻与开机自启
对于 NetBird 服务端来说，你不需要像配置传统软件那样手动编写 /etc/systemd/system/netbird.service。官方安装脚本生成的 Docker Compose 配置中已经自带了容器保活策略。你只需要确保服务器本身的 Docker 守护进程设置为开机启动即可：

sudo systemctl enable docker
sudo systemctl start docker

只要 Docker 服务在运行，NetBird 的所有服务端容器（包括数据库、面板、中继组件等）就会自动常驻后台并跟随服务器开机自启，省去了大量的手动运维工作。

参考文献

• NetBird Self-Hosting Quickstart
• How NetBird Works

1. 规则引擎执行架构（Match-Select-Act）

首先要理解 事实 (Fact) 与 规则 (Rule) 是如何交汇的。

graph LR
    subgraph 业务端
        Fact[Facts 事实对象]
        Rules[Rules 规则描述]
    end
    
    subgraph 规则引擎运行时核心
        WM[(工作内存<br/>Working Memory)]
        PM[(规则内存<br/>Production Memory)]
        Matcher{Rete 模式匹配器<br/>Pattern Matcher}
        Agenda[议程控制<br/>Agenda]
    end
    
    Fact -->|1. Insert 断言插入| WM
    Rules -->|2. 加载编译入库| PM
    
    WM -->|事实进入| Matcher
    PM -->|构建网络| Matcher
    
    Matcher -->|3. 条件匹配成功的激活项| Agenda
    Agenda -->|4. 按优先级解决冲突并执行| Action[触发操作逻辑 / RHS]
    Action -.->|5. 可能会产生或修改事实| WM

执行分三个阶段：

• 匹配 (Match)：Fact 插入工作内存，通过 Rete 网络与规则条件建立绑定。
• 选择 (Select)：匹配成功的结果放入 Agenda，根据优先级决定执行顺序。
• 执行 (Act)：触发动作，可能引起新的事实变更，从而触发新一轮匹配。

2. Rete 网络结构

当规则包含多个条件时，Rete 会构建多层网络，分为两部分：

• Alpha Network：对单个事实做属性过滤
• Beta Network：将多个 Alpha 节点的结果做 Join 连接

graph TD
    subgraph AlphaLayer [Alpha层 单条件过滤]
        Root[RootNode<br/>数据总入口]
        OTN[ObjectType Node<br/>对象类型分发]
        
        Root --> OTN
        OTN --> Alpha1[Alpha 1: 地区=北京]
        OTN --> Alpha2[Alpha 2: 车龄<10年]
        OTN --> Alpha3[Alpha 3: 车价>1万元]
    end

    subgraph BetaLayer [Beta层 条件组合 / Join]
        Beta1((Beta Node 1<br/>地区 + 车龄))
        Alpha1 -->|左输入| Beta1
        Alpha2 -->|右输入| Beta1

        Beta2((Beta Node 2<br/>前置结果 + 车价))
        Beta1 -->|左输入| Beta2
        Alpha3 -->|右输入| Beta2
    end

    subgraph ActionLayer [执行区]
        Terminal[Terminal Node<br/>条件满足,执行规则]
        Beta2 --> Terminal
    end

    style Alpha1 fill:#e6f7ff,stroke:#1890ff
    style Alpha2 fill:#e6f7ff,stroke:#1890ff
    style Alpha3 fill:#e6f7ff,stroke:#1890ff
    style Beta1 fill:#f9f0ff,stroke:#722ed1,shape:circle
    style Beta2 fill:#f9f0ff,stroke:#722ed1,shape:circle
    style Terminal fill:#fffbe6,stroke:#faad14

• 增量匹配：Beta1 会缓存”地区+车龄”的组合结果。后续新增”车价”事实时，只需与 Beta1 的缓存做 Join，不必从头遍历。

3. 为什么要分 Alpha 和 Beta 两层

如果不做拆分，每来一条新事实就要把所有规则的所有条件重新算一遍，复杂度是 O(规则数 × 条件数)。

拆成两层后：

Alpha 层做独立过滤：每个条件单独检查一个属性，结果缓存在 Alpha 内存中。

• 新事实进来，只触发属性匹配的 Alpha 节点，其他节点不动
• 多条规则如果共用同一个条件（比如都要检查 age < 10），共享同一个 Alpha 节点，只算一次

Beta 层做组合连接：把多个 Alpha 的结果按 ID 做 Join，中间结果缓存在 Beta 内存中。

• 已经组合好的部分结果不需要重算。比如”地区+车龄”已经 Join 好了，后面”车价”事实到了，直接拿缓存做第二次 Join
• 多条规则如果前几个条件相同，共享同一条 Beta 路径，只在分歧点才分叉

类比数据库：Alpha 相当于 WHERE 过滤，Beta 相当于 JOIN 连接，Alpha/Beta 内存相当于缓存的中间结果。不分层就等于每次全表扫描加嵌套循环 Join；分层后相当于建了索引并缓存中间结果，只对增量部分做计算。

4. 编译与匹配推演

在 Rete 算法中，事实 (Fact) 用”三元组”表示：(标识符 ^ 属性 值)，简写为 (FactID, Attribute, Value)。

以车辆投保规则为例：

事实集（进入工作内存）：

• w1: (car1, area, "北京")
• w2: (car1, age, 9)
• w3: (car1, price, 15000)

规则条件（LHS / Pattern）：

• c1: 匹配地区 (?, area, "北京")
• c2: 匹配车龄 (?, age, <10)
• c3: 匹配车价 (?, price, >10000)

第一阶段：创建 Rete 网络（编译期）

引擎在事实产生前，读取规则库生成 Rete 网络：

1. RootNode：创建全局唯一的入口节点，所有事实从这里进入。
2. Alpha 1：取条件 c1，生成 AlphaNode1 检查 attr == area && value == "北京"，挂在 Root 下，附带 Alpha 内存。
3. Alpha 2：取条件 c2，生成 AlphaNode2 检查 age < 10，同样挂在 Root 下。
4. Beta 1：创建 BetaNode1，左输入接 AlphaNode1，右输入接 AlphaNode2。
5. Alpha 3 + Beta 2：取条件 c3，生成 AlphaNode3 检查 price > 10000；创建 BetaNode2，左输入接 BetaNode1 的输出，右输入接 AlphaNode3。
6. Terminal：将规则动作封装为 TerminalNode，接在 BetaNode2 之后。

第二阶段：匹配过程（运行时）

网络构建完成后，每条新事实进入网络，依次经过 Alpha 过滤（Select）和 Beta 连接（Join）：

1. 插入 w1: (car1, area, "北京")
   • w1 从 RootNode 广播到所有 Alpha 节点。
   • AlphaNode1 匹配成功（area == "北京"），将 w1 存入 Alpha 内存，并通知下游 BetaNode1。
   • AlphaNode2、AlphaNode3 属性不匹配，丢弃。
2. 插入 w2: (car1, age, 9)
   • AlphaNode2 匹配成功（9 < 10），存入内存，通知 BetaNode1。
   • 首次 Join：BetaNode1 检查左侧（AlphaNode1 内存中有 w1）和右侧（AlphaNode2 内存中有 w2），两者 ID 均为 car1，Join 成功，生成组合 (w1, w2) 存入 Beta 内存，传递给 BetaNode2。
3. 插入 w3: (car1, price, 15000)
   • AlphaNode3 匹配成功（15000 > 10000），存入内存，通知 BetaNode2。
   • 二次 Join：BetaNode2 左侧已有来自 BetaNode1 的 (w1, w2)，右侧新到 w3，ID 一致，Join 成功，生成完整绑定集 (w1, w2, w3)。
4. 触发动作
   • (w1, w2, w3) 到达 TerminalNode，所有条件满足，执行规则动作。

5. Python 代码模拟

下面将 Root → Alpha → Beta(层1) → Beta(层2) → Terminal 的网络用 Python 实现，观察数据逐层传递与 Join 组合的过程。

from typing import Any, Callable, List, Tuple, Union

# ---- 数据结构 ----

class Fact:
    """三元组事实: (标识符, 属性, 值)"""
    def __init__(self, id: str, attr: str, value: Any) -> None:
        self.id: str = id
        self.attr: str = attr
        self.value: Any = value

    def __repr__(self) -> str:
        return f"({self.id}, {self.attr}, {self.value})"

# Token 是在网络中流转的绑定集，可以是单个 Fact 或 Fact 元组
Token = Union[Fact, Tuple[Fact, ...]]

def token_id(t: Token) -> str:
    """从 Token 中提取标识符，用于 Join 时的 ID 一致性校验"""
    return t.id if isinstance(t, Fact) else t[0].id

def token_to_tuple(t: Token) -> Tuple[Fact, ...]:
    return (t,) if isinstance(t, Fact) else t

# ---- 节点定义 ----

class ReteNode:
    def __init__(self, name: str) -> None:
        self.name: str = name
        self.children: List['ReteNode'] = []
        self.memory: List[Token] = []

    def pass_to_children(self, token: Token) -> None:
        print(f"  [放行] \033[92m{self.name}\033[0m")
        for child in self.children:
            child.receive(token)

    def receive(self, token: Token) -> None:
        pass

# Alpha 节点：单条件过滤
class AlphaNode(ReteNode):
    def __init__(self, name: str, attr: str, condition: Callable[[Any], bool]) -> None:
        super().__init__(name)
        self.attr: str = attr
        self.condition: Callable[[Any], bool] = condition

    def receive(self, token: Token) -> None:
        if isinstance(token, Fact) and token.attr == self.attr and self.condition(token.value):
            self.memory.append(token)
            self.pass_to_children(token)

# Beta 节点：Join 连接（按标识符做等值连接）
class BetaNode(ReteNode):
    def __init__(self, name: str, left_node: ReteNode, right_node: ReteNode) -> None:
        super().__init__(name)
        self.left: ReteNode = left_node
        self.right: ReteNode = right_node
        left_node.children.append(self)
        right_node.children.append(self)

    def receive(self, token: Token) -> None:
        """当左或右有新数据到达时，与对侧内存做 Join"""
        incoming_id = token_id(token)

        # 在左右两侧中寻找 ID 匹配的已有缓存
        left_matches = [m for m in self.left.memory if token_id(m) == incoming_id]
        right_matches = [m for m in self.right.memory if token_id(m) == incoming_id]

        if left_matches and right_matches:
            # 将左侧绑定集与右侧绑定集合并为更大的元组
            combined = token_to_tuple(left_matches[0]) + token_to_tuple(right_matches[0])
            self.memory.append(combined)
            self.pass_to_children(combined)

# 终端节点：触发规则动作
class TerminalNode(ReteNode):
    def __init__(self, name: str, action_func: Callable[[Tuple[Fact, ...]], None]) -> None:
        super().__init__(name)
        self.action = action_func

    def receive(self, token: Token) -> None:
        facts = token_to_tuple(token)
        print(f"\n=> 🎯 【规则激活】{self.name}")
        print(f"   匹配绑定集: {facts}")
        self.action(facts)

# ============ 构建 Rete 网络 ============

root = ReteNode("RootNode")

# [Layer 1] Alpha 节点
alpha_area = AlphaNode("Alpha[地区=北京]", 'area', lambda v: v == '北京')
alpha_age = AlphaNode("Alpha[车龄<10年]", 'age', lambda v: v < 10)
alpha_price = AlphaNode("Alpha[车价>1万]", 'price', lambda v: v > 10000)
root.children.extend([alpha_area, alpha_age, alpha_price])

# [Layer 2] Beta1: Join 地区 + 车龄
beta_1 = BetaNode("Beta1[地区+车龄]", alpha_area, alpha_age)

# [Layer 3] Beta2: Join Beta1 结果 + 车价
beta_2 = BetaNode("Beta2[合规+车价]", beta_1, alpha_price)

# Terminal: 执行动作
terminal = TerminalNode(
    "Terminal[推荐高价值投保套餐]",
    lambda facts: print(f"   ===> 执行动作：为 {facts[0].id} 推荐北京高价值投保套餐")
)
beta_2.children.append(terminal)

# ============ 运行测试 ============

print("1. 录入事实：地区...")
root.pass_to_children(Fact('car1', 'area', '北京'))
# Alpha[地区] 匹配，存入内存；Beta1 右侧为空，阻断

print("\n2. 录入事实：车龄...")
root.pass_to_children(Fact('car1', 'age', 9))
# Alpha[车龄] 匹配；Beta1 左右均有 car1 的数据，Join 成功 → 组合 (w1, w2)
# Beta2 右侧 alpha_price 为空，阻断

print("\n3. 录入事实：车价...")
root.pass_to_children(Fact('car1', 'price', 15000))
# Alpha[车价] 匹配；Beta2 左侧有 (w1,w2)，右侧有 w3，ID 一致 → Join 成功
# 完整绑定集 (w1, w2, w3) 到达 Terminal，触发动作

6. 优缺点

优点

1. 规则间共享节点：不同规则如果有相同的条件模式，会共享 Alpha/Beta 节点。某个节点被 N 条规则共用，该节点上的匹配效率提升 N 倍。
2. 增量匹配：Alpha 内存和 Beta 内存缓存了中间结果。事实集变化不大时，大部分节点状态不需要重算，只处理增量部分。
3. 匹配速度与规则数量无关：事实在网络中传播时，不满足条件就被拦截，不会继续向下。规则再多，单条事实经过的路径长度是固定的。

缺点

1. 事实删除开销大：删除事实时，除了要做和添加相同的计算外，还需要在内存中查找并清除相关的缓存记录。
2. 内存占用可能指数级增长：Beta 内存存储的中间组合结果，会随着规则条件数和事实数量增长而膨胀。规则和事实很多时，可能耗尽内存。

实践建议

一句话总结：Rete 用空间换时间——通过缓存中间结果加速匹配，代价是内存开销大。适合事实集相对稳定、规则频繁执行的场景。

相关链接

• RulEuler：基于 Rete 算法的开源规则引擎：https://caritasem.github.io/2026/03/ruleuler-rule-engine-introduction/
• 开源规则引擎实践：https://github.com/labulakalia/ibm_bak/blob/main/ibm_articles/%E5%BC%80%E6%BA%90%E8%A7%84%E5%88%99%E6%B5%81%E5%BC%95%E6%93%8E%E5%AE%9E%E8%B7%B5.md

原理

RDP 协议就是远程桌面用的协议，mstsc.exe 通过它连目标机器、发送凭据、建立会话。这个项目用了基于 node-rdpjs 改造的协议库，等于用 Node.js 实现了一个精简版 RDP 客户端。连接目标设成 127.0.0.1:3389（连自己），把用户名密码发过去，Windows 就会为该账号创建会话。登录完成后客户端退出，但会话保持。

再配一个 VBS 脚本把控制台窗口藏掉，扔到开机启动里，就实现了全自动、无感知的后台登录。

使用方式

1. 安装依赖

机器上需要先有 Node.js：

git clone https://github.com/sibosend/rdp-auto-login.git
cd rdp-auto-login
npm install

2. 修改配置

编辑 index.js，把用户名密码改成目标账号的：

const protocol = require('./protocol');  

const c = protocol.rdp.createClient({ 
    domain : '',                  // 域用户填域名，本地用户留空
    userName : 'your_username',   // 改成目标账号
    password : 'your_password',   // 改成对应密码
    enablePerf : true,
    autoLogin : true,
    decompress : false,
    screen : { width : 1920, height : 1200 },
    locale : 'en',
    logLevel : 'INFO'
}).connect('127.0.0.1', 3389)     // 连本机，一般不用改

改完先跑一下验证：

npm run start

控制台打出 connected 就说明成功了。打开任务管理器切到”用户”标签页，应该能看到目标账号已在线。

3. 打包成 exe

生产环境不想装 Node.js，用 pkg 打包成独立可执行文件：

npm install -g pkg
pkg -t node18-win-x64 index.js
mv index.exe RDP-logon.exe

4. 后台静默运行

直接双击 exe 会弹黑框窗口。项目里带了一个 RDP-logon.vbs，用 WScript.Shell 以隐藏窗口方式启动 exe：

objShell.Run """" & exePath & ".exe""" & strArguments, 0, False
' 第二个参数 0 = 隐藏窗口，False = 不等待进程结束

部署步骤：

1. 把 RDP-logon.exe 和 RDP-logon.vbs 放同一个目录
2. Win+R 输入 shell:startup，打开启动目录
3. 把 RDP-logon.vbs（或其快捷方式）丢进去

这样每次宿主账号登录时，VBS 会自动在后台把目标账号登上去。

注意事项

• 远程桌面必须开启 — 系统属性 → 远程 → 勾选”允许远程连接到此计算机”，否则 3389 端口没在监听。
• 多用户并发 — Windows Server 天然支持多会话；Win10/11 专业版默认只允许一个远程会话，需要 RDPWrap 之类的工具解除限制，否则新登录会踢掉当前用户。
• 安全性 — 密码明文写在 index.js 中，打包后不容易直接看到但也不算安全。如有要求，建议加密或从配置文件读取。

相关链接

• GitHub 仓库：https://github.com/sibosend/rdp-auto-login

项目背景

RulEuler 基于 URule 2.1.6（Bstek 开源版）二次开发。URule 核心引擎成熟可靠，但 JCR 存储模型对多数开发者不够直观。RulEuler 在保留核心引擎的基础上做了以下改进：

适用场景

• 风控决策 — 信用评分、反欺诈规则、额度审批
• 业务审批 — 多级审批流程、条件分支路由
• 动态定价 — 促销规则、折扣策略、阶梯计价
• 资源分配 — 机位分配、工单派发、负载均衡策略
• 合规校验 — 数据校验规则、业务合规检查

核心特性

• 可视化规则编辑 — 决策表、决策树、决策流、评分卡，拖拽式配置
• REA 文本编辑器 — 自然语言风格的表达式编写规则，效率更高

• Rete 算法驱动 — 高效模式匹配，适合大量规则并发执行
• 知识包热更新 — 规则修改后客户端自动加载，无需重启
• 自动测试 — 基于路径覆盖自动生成测试用例，回归比对输出变化

• RBAC 权限控制 — 用户、角色、项目级权限管理

架构概览

RulEuler 由两个独立部署的服务组成，通过 MySQL 共享规则数据：

浏览器 --> 管理后台 (ruleuler-server + ruleuler-admin) :16009
业务系统 --> 规则执行 (ruleuler-client) :16001
管理后台 --> MySQL
规则执行 --> MySQL

• 管理后台 — 规则编辑、项目管理、权限控制
• 规则执行 — 加载知识包，执行决策流，对外提供 REST API

快速体验

30 秒用 Docker 跑起来：

git clone https://github.com/sibosend/ruleuler.git
cd ruleuler
cp .env.example .env
docker compose up -d --build

启动完成后访问 http://localhost:16009/admin/，
调用规则示例：

curl -X POST http://localhost:16001/process/airport_gate_allocation_db/gate_pkg/gate_allocation_flow \
  -H 'Content-Type: application/json' \
  -d '{
  "FlightInfo": {
    "aircraft_type": "A380",
    "arrival_time": 8,
    "is_international": true,
    "passenger_count": 260
  },
  "GateResult": {}
}'

相关链接

• 项目主页：https://sibosend.github.io/ruleuler/
• GitHub 仓库：https://github.com/sibosend/ruleuler

原理概述

整体链路如下：

Kiro IDE 登录 → 本地生成 token 文件
    → CLIProxyAPI Plus 导入 token（--kiro-import）
    → 启动本地代理服务（127.0.0.1:8317）
    → CC Switch 配置 provider 指向该代理
    → Claude Code / VSCode Claude Code 扩展正常使用

核心思路：Kiro 登录后会在本地缓存一份 AWS SSO token，CLIProxyAPI Plus 能读取并转换为兼容 Claude API 的代理服务，CC Switch 则负责管理和切换这些配置。

前置准备

• 已安装并登录过 Kiro IDE（确保本地已生成 token）
• 已安装 Claude Code CLI（npm install -g @anthropic-ai/claude-code）
• 已安装 CC Switch（GitHub 下载）
• 已下载 CLIProxyAPI Plus（GitHub 下载）

第一步：确认 Kiro Token 位置

登录 Kiro IDE 后，token 文件会自动生成在以下路径：

文件内容大致如下：

{
    "accessToken": "aoa....",
    "expiresIn": 3600,
    "refreshToken": "aor....",
    "tokenType": "Bearer"
}

如果你从未登录过 Kiro，需要先打开 Kiro IDE 完成一次登录（Google 或 GitHub 均可）。

第二步：配置 CLIProxyAPI Plus

2.1 初始化配置文件

解压 CLIProxyAPI Plus 后，进入目录：

cp config.example.yaml config.yaml

编辑 config.yaml，最小配置如下：

port: 8317

auth-dir: "~/.cli-proxy-api"

request-retry: 3

quota-exceeded:
  switch-project: true
  switch-preview-model: true

api-keys:
  - "your-custom-api-key"

remote-management:
  allow-remote: false
  secret-key: "your-management-key"
  disable-control-panel: false

其中 api-keys 是你自定义的密钥，后续 CC Switch 中需要填写。

2.2 导入 Kiro Token

在 CLIProxyAPI Plus 目录下执行：

# macOS / Linux
./cli-proxy-api-plus --kiro-import

# Windows
cli-proxy-api-plus.exe --kiro-import

成功后会看到类似输出：

✓ Imported Kiro token from IDE (Provider: )
Authentication saved to /Users/<用户名>/.cli-proxy-api/kiro-imported-xxxx.json
Imported as kiro-imported
Kiro token import successful!

如果提示找不到 token 文件，请确认 Kiro IDE 已登录，并检查上述路径是否存在 kiro-auth-token.json。

2.3 启动代理服务

# macOS / Linux
./cli-proxy-api-plus

# Windows
cli-proxy-api-plus.exe

启动后可访问管理界面：http://127.0.0.1:8317/management.html

在「中心信息」栏目中可以看到已导入的 Kiro 模型列表，包括：

• kiro-claude-opus-4-5-agentic
• kiro-claude-sonnet-4-5-agentic
• kiro-claude-haiku-4-5-agentic

第三步：在 CC Switch 中配置 Provider

打开 CC Switch，点击「Add Provider」，选择自定义配置。

关键的环境变量配置如下：

{
    "ANTHROPIC_AUTH_TOKEN": "your-custom-api-key",
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:8317",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "kiro-claude-haiku-4-5-agentic",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "kiro-claude-opus-4-5-agentic",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "kiro-claude-sonnet-4-5-agentic",
    "ANTHROPIC_MODEL": "kiro-claude-opus-4-5-agentic"
}

说明：

• ANTHROPIC_AUTH_TOKEN：填写你在 config.yaml 中设置的 api-keys
• ANTHROPIC_BASE_URL：指向 CLIProxyAPI Plus 的本地地址
• 模型名称需要使用 Kiro 专属的名称映射（带 kiro- 前缀），因为 Kiro 的模型名与标准 Claude 模型名不同

配置完成后，在 CC Switch 中点击「Enable」激活该 Provider。

第四步：在 Claude Code 中验证

重启终端，运行 Claude Code：

claude

此时 Claude Code 会通过本地代理访问 Kiro 的 Claude Opus 模型。可以用 /model 命令确认当前使用的模型。

第五步：在 VSCode 中使用 Claude Code 扩展

如果你使用 VSCode 的 Claude Code 扩展，同样可以享受到代理后的模型。CC Switch 的配置对 Claude Code CLI 和 VSCode 扩展都生效。

在 VSCode 中打开 Claude Code 面板，即可正常使用 Kiro 的 Opus 模型进行编码辅助。

Token 过期处理

Kiro 的 token 有效期为 3600 秒（1 小时）。在第一次登录成功后（比如使用 kiro-cli 等方式），CLIProxyAPI 会自动处理每小时的 token 更新，无需手动干预。

如果自动刷新未生效，也可以手动重新导入：

1. 打开 Kiro IDE（会自动刷新 token）
2. 重新执行 ./cli-proxy-api-plus --kiro-import

前提是 Kiro IDE 保持打开状态，这样 token 会被自动续期。

常见问题

Q: 导入时提示找不到 token 文件？

确保已打开 Kiro IDE 并完成登录。如果路径不存在，可以手动创建 ~/.aws/sso/cache/ 目录，然后将获取到的 token JSON 文件重命名为 kiro-auth-token.json 放入。

Q: Claude Code 报连接错误？

检查 CLIProxyAPI Plus 是否正在运行，以及端口 8317 是否被占用。可以用 curl http://127.0.0.1:8317/v1/models 测试连通性。

Q: 模型名称不对？

Kiro 的模型名称带有 kiro- 前缀和 -agentic 后缀，必须在 CC Switch 的环境变量中正确映射，否则 Claude Code 会找不到模型。

参考链接

• CLIProxyAPI 系列教程（配置详解）
• CLIProxyAPI 项目介绍
• 中转转发接入篇
• GUI 管理界面
• Docker 部署
• Kiro Token 代理到 CC 的实践记录
• CC Switch GitHub
• CLIProxyAPI Plus GitHub

本文记录两件事：

• 用 VS Code（Overleaf Workshop 插件）把项目同步到本地编辑，并用 Copilot 做润色/改写等 AI 协作。

1. VS Code 打通 Overleaf（Overleaf Workshop）

step 1：安装插件

在 VS Code 扩展里搜索并安装：Overleaf Workshop。

类 VS Code 编辑器一般也可用（例如 Antigravity），步骤基本一致。

step 2：用 Cookie 登录（相当于以 co-author 身份接入）

插件目前常见的方式是「Login with Cookie」。从网页端 Overleaf 取 Cookie：

1) 打开 Overleaf 网页端，F12 -> DevTools -> Network。
2) 过滤 /project，然后刷新页面。
3) 点开对应请求，在 Request Headers 里找到 Cookie，复制完整内容。

回到 VS Code：

• Overleaf Workshop 侧边栏 -> Login with Cookie -> 粘贴 Cookie。

step 3：同步项目到本地并编译

登录成功后，插件会列出你的项目（含已删除的项目）。选择一个项目打开，就会把 .tex 等文件同步到本地工作区。

在本地 .tex 文件里触发编译即可看到和网页端类似的效果。

编译快捷键（参考文章）：macOS 为 Option+Command+V（Windows/Linux 按插件默认/自定义为准）。

常见问题：连的是哪个 Overleaf？

如果你是自建 Overleaf（本地 or 内网），需要在插件/配置里把 Overleaf 服务器地址指向你的服务。

（不同版本的插件入口可能略有差异，核心就是：让插件访问到你的 Overleaf 域名/端口，然后再用 Cookie 做登录。）

2. Copilot 辅助写 LaTeX（润色/改写/结构化）

有了 VS Code 后，AI 协作基本等价于「对着本地 .tex 文件用 Copilot」。常用用法：

• 让 Copilot 帮你把口语化表达改成更学术/更简洁的句式。
• 让 Copilot 生成表格/公式骨架（你再补数据）。
• 让 Copilot 按某个会议/期刊风格做引用格式微调（仍建议你最终用 bibtex/biblatex 管理）。

常用latex 模版

• 清华大学论文
• 简历模版

本文记录单域名（A/普通域名）使用 Certbot 自动签发并自动续期的实施过程，着重讲述基于 --nginx 的常见流程与注意事项。泛域名（Wildcard）证书需要 DNS-01 验证（DNS API 或手动添加 TXT 记录），不在本文讨论范围。

安装 Certbot

以Ubuntu 系统为例：

sudo apt update
sudo apt install certbot python3-certbot-nginx

更多安装方式请参考 Certbot 官方文档。

单域名证书：申请流程

假设要为 test.example.com 申请证书，并且 Nginx 已经配置好对应的 server_name 并能通过 80 端口被外网访问。

1. 使用 nginx 插件自动完成验证与配置（Certbot 会尝试修改 Nginx 配置并在成功后加入 SSL 配置）：

sudo certbot --nginx -d test.example.com

1. 过程要点：
   • Certbot 会先验证域名（HTTP-01），要求 80 端口能到达你的 Nginx 服务。
   • 成功后，Certbot 会在 Nginx 对应的 server 块中插入由它管理的 listen 443 ssl / ssl_certificate / ssl_certificate_key 等配置；同时可选地添加 80→443 的重定向块。

示例（申请前 Nginx 简化配置）：

upstream backend.gh {
    server 127.0.0.1:3000;
}

server {
    listen 80;
    server_name test.example.com;

    location / {
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_pass http://backend.gh;
    }
}

申请成功后，Certbot 会生成类似的受管理配置（只摘要）：

server {
    listen 443 ssl; # managed by Certbot
    server_name test.example.com;

    ssl_certificate /etc/letsencrypt/live/test.example.com/fullchain.pem; # managed by Certbot
    ssl_certificate_key /etc/letsencrypt/live/test.example.com/privkey.pem; # managed by Certbot
    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot

    location / {
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_pass http://backend.gh;
    }
}

server {
    if ($host = test.example.com) {
        return 301 https://$host$request_uri;
    }

    listen 80; # managed by Certbot
    server_name test.example.com;
    return 404; # managed by Certbot
}

注意：Certbot 标记为 “managed by Certbot” 的行不应手动删除或随意修改（除非你清楚后果），否则升级或续期时可能出现冲突。

你可以用下面命令查看已安装的证书和路径：

sudo certbot certificates

自动续期

Let’s Encrypt 的证书有效期为 90 天，推荐启用自动续期（Certbot 默认会在安装时创建 systemd timer / cron 任务，取决于安装方式）。常见验证方式：

1. 先做一次模拟续期验证：

sudo certbot renew --dry-run

1. 如果模拟续期成功，可以启用自动续期：

• 推荐（现代系统）：使用 systemd timer（通常 Certbot 安装会自动启用）。检查状态：

systemctl list-timers | grep certbot

• 传统方法：加入 crontab（如果你更习惯或系统没有 systemd）：

0 2 * * * * /usr/bin/certbot renew --quiet

该 cron 表示每日凌晨 02:00 执行一次续期检查。certbot renew 只有在证书将于 30 天内到期时才会实际尝试续期。

1. 续期后 Certbot 会自动替换 /etc/letsencrypt/live/<domain> 下的证书文件，通常无需重载 Nginx，因为 Certbot 会在续期时尝试触发必要的 reload。如果你自定义了部署脚本，确保在替换证书后重载 Nginx：

sudo systemctl reload nginx

其他提示

• 如果你使用代理、Cloudflare 或者负载均衡器，请确保 HTTP-01 挑战能被 LetsEncrypt 的验证服务器访问到（或考虑使用 DNS-01 验证）。
• 泛域名（Wildcard）证书需要 DNS-01 验证，通常借助 DNS 提供商 API 自动添加 TXT 记录；此流程和本文不同。
• 遇到问题时查看日志：/var/log/letsencrypt/letsencrypt.log，或在命令行加入 -v 获取更多调试信息。

参考：

1. https://www.cnblogs.com/michaelshen/p/18538178

While setting up LightGBM on my M1 Mac, I discovered that the default pip install lightgbm command does not work due to compatibility issues with Apple Silicon and libomp dependencies.

After trying various fixes, including setting environment variables and reinstalling libomp via Homebrew, I still encountered installation errors with:

pip install lightgbm --no-binary :all:

After some research, I found a solution that worked: creating a new Conda environment and installing LightGBM using Conda-Forge:

conda install \
    --yes \
    -c conda-forge \
    'lightgbm>=4.6.0'

This approach successfully installed LightGBM without further issues.

For more details and troubleshooting options, I found this Stack Overflow discussion useful.

Ref:

1. https://katieminjoo.github.io/posts/InstallLGBMonMacM1/