<?xml version="1.0" encoding="UTF-8"?><rss version="2.0" xmlns:content="http://purl.org/rss/1.0/modules/content/"><channel><title>QAQ</title><description>欢迎来到世界</description><link>https://blog.0v0.uno/</link><language>zh_CN</language><item><title>不同网络下的 OneBot WebSocket 通信</title><link>https://blog.0v0.uno/posts/deploy/astrbot-adapter-different-network/</link><guid isPermaLink="true">https://blog.0v0.uno/posts/deploy/astrbot-adapter-different-network/</guid><description>NapCat/SnowLuma 和 AstrBot 不在同一 Docker 网络时，通过宿主机 6199 端口和 host.docker.internal 建立 OneBot WebSocket 连接。</description><pubDate>Sun, 15 Nov 2026 07:48:24 GMT</pubDate><content:encoded>&lt;p&gt;NapCat/SnowLuma 和 AstrBot 不在同一个 Docker 网络时，容器名 &lt;code&gt;astrbot&lt;/code&gt; 解析不到，需要让 AstrBot 把 &lt;code&gt;6199&lt;/code&gt; 暴露到宿主机，客户端再通过宿主机地址连接。&lt;/p&gt;
&lt;p&gt;适用场景：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Windows 上的 NapCat 连接远程 Linux 服务器上的 AstrBot&lt;/li&gt;
&lt;li&gt;NapCat/SnowLuma 在 &lt;code&gt;1panel-network&lt;/code&gt;，AstrBot 在 &lt;code&gt;astrbot_astrbot-network&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;两个容器分属不同的 Compose 项目&lt;/li&gt;
&lt;/ul&gt;
&lt;h1&gt;1. AstrBot 暴露 6199&lt;/h1&gt;
&lt;p&gt;&lt;code&gt;6199&lt;/code&gt; 是 ==AstrBot=={.primary} 的反向 WebSocket 端口，不是 NapCat/SnowLuma 的端口。&lt;/p&gt;
&lt;p&gt;如果 AstrBot 是 1Panel 容器，在容器端口设置里加 &lt;code&gt;6199&lt;/code&gt;：&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/adapter/napcat/astrbot-port-6199.png&quot; alt=&quot;AstrBot 暴露 6199 端口 w-100%&quot; title=&quot;AstrBot 的 6185 和 6199 都映射到宿主机，网络是 astrbot_astrbot-network&quot; /&gt;&lt;/p&gt;
&lt;p&gt;如果是 Compose，在 &lt;code&gt;astrbot&lt;/code&gt; 服务的 &lt;code&gt;ports&lt;/code&gt; 下加：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ports:
  - &quot;6185:6185&quot;
  - &quot;6199:6199&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;改完后重启 AstrBot。&lt;/p&gt;
&lt;p&gt;:::caution[6199 不要对公网开放]
云安全组和 1Panel 防火墙只放行客户端的出口 IP。不要把 &lt;code&gt;6199&lt;/code&gt; 开放给全部 IPv4 地址，否则任何人都能尝试连接 AstrBot 的反向 WebSocket。
:::&lt;/p&gt;
&lt;h1&gt;2. 配置 NapCat&lt;/h1&gt;
&lt;p&gt;判断是不是「同一网络」，看的是 ==Docker 网络名和它的子网=={.primary}，不是只看 IP。先上下对比 1Panel 里两个容器的网络设置：&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;AstrBot 容器：&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/adapter/napcat/astrbot-port-6199.png&quot; alt=&quot;AstrBot 容器使用 astrbot_astrbot-network w-100%&quot; title=&quot;AstrBot 的 6185 和 6199 都映射到宿主机，网络是 astrbot_astrbot-network&quot; /&gt;&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;NapCat 容器：&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/adapter/napcat/container-ports.png&quot; alt=&quot;NapCat 容器使用 1panel-network w-100%&quot; title=&quot;端口 3000-3001、6099，网络 1panel-network&quot; /&gt;&lt;/p&gt;
&lt;p&gt;一个是 &lt;code&gt;astrbot_astrbot-network&lt;/code&gt;（172.19.0.0/16），一个是 &lt;code&gt;1panel-network&lt;/code&gt;（172.18.0.0/16）。网络名不同，子网也不同。&lt;/p&gt;
&lt;p&gt;IP 结果只是辅助，真正的依据还是上面的网络名：&lt;/p&gt;
&lt;p&gt;:::grid{columns=2}&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/adapter/napcat/ip-same-network.png&quot; alt=&quot;同一网络：AstrBot 和 NapCat 都在 astrbot_astrbot-network（172.19.0.0/16）&quot; title=&quot;同一网络：都在 astrbot_astrbot-network，AstrBot 172.19.0.2，NapCat 172.19.0.3&quot; /&gt;&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/adapter/napcat/ip-cross-network.png&quot; alt=&quot;不同网络：AstrBot 在 astrbot_astrbot-network（172.19.0.0/16），NapCat 在 1panel-network（172.18.0.0/16）&quot; title=&quot;不同网络：AstrBot 172.19.0.2，NapCat 172.18.0.2；网络名不同，子网也不同&quot; /&gt;&lt;/p&gt;
&lt;p&gt;:::&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;对比项&lt;/th&gt;
&lt;th&gt;同一网络&lt;/th&gt;
&lt;th&gt;不同网络&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;AstrBot 网络&lt;/td&gt;
&lt;td&gt;&lt;code&gt;astrbot_astrbot-network&lt;/code&gt;（172.19.0.0/16）&lt;/td&gt;
&lt;td&gt;&lt;code&gt;astrbot_astrbot-network&lt;/code&gt;（172.19.0.0/16）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;NapCat 网络&lt;/td&gt;
&lt;td&gt;同一个 &lt;code&gt;astrbot_astrbot-network&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;1panel-network&lt;/code&gt;（172.18.0.0/16）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;能否用 &lt;code&gt;astrbot&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;可以&lt;/td&gt;
&lt;td&gt;不行，要走宿主机地址&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;确认不在同一个 Docker 网络后，再给 NapCat 加主机映射。Docker 容器里的 &lt;code&gt;host.docker.internal&lt;/code&gt; 默认不一定可用。Compose 写法：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  napcat:
    extra_hosts:
      - &quot;host.docker.internal:host-gateway&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;1Panel 里则在 NapCat 容器的「主机映射」中添加：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;主机名&lt;/th&gt;
&lt;th&gt;IP&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;host.docker.internal&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;host-gateway&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/adapter/napcat/host-gateway.png&quot; alt=&quot;NapCat 添加 host.docker.internal 映射 w-100%&quot; title=&quot;主机名 host.docker.internal，值 host-gateway&quot; /&gt;&lt;/p&gt;
&lt;p&gt;不同网络时，两个容器不在同一个 Docker 网络（子网也不同，见上方对比）。&lt;/p&gt;
&lt;p&gt;如果 NapCat 必须留在 &lt;code&gt;1panel-network&lt;/code&gt;（1Panel 自带、已有自己子网的网络），在 1Panel 里这样选：&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/adapter/napcat/container-network.png&quot; alt=&quot;NapCat 使用 1panel-network w-100%&quot; title=&quot;NapCat 的网络选择 1panel-network&quot; /&gt;&lt;/p&gt;
&lt;p&gt;Windows 上的 NapCat 不需要 Docker 主机映射，确认能访问 AstrBot 的 &lt;code&gt;6199&lt;/code&gt; 即可。&lt;/p&gt;
&lt;h1&gt;3. Docker Compose 配置&lt;/h1&gt;
&lt;p&gt;下面四份配置都用于不同网络：客户端单独一个网络，通过 &lt;code&gt;host.docker.internal&lt;/code&gt; 访问宿主机上的 AstrBot &lt;code&gt;6199&lt;/code&gt;。&lt;/p&gt;
&lt;h2&gt;3.1 NapCat 单独部署（napcat-network）&lt;/h2&gt;
&lt;p&gt;AstrBot 已经部署好，只新增 NapCat：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  napcat:
    image: mlikiowa/napcat-docker:latest
    container_name: napcat
    restart: always
    environment:
      - NAPCAT_UID=0
      - NAPCAT_GID=0
+    extra_hosts:
+      - &quot;host.docker.internal:host-gateway&quot;
    ports:
      - &quot;3000:3000&quot;
      - &quot;3001:3001&quot;
      - &quot;6099:6099&quot;
    volumes:
      - ./napcat/config:/app/napcat/config
      - ./ntqq:/app/.config/QQ
      - astrbot-data:/AstrBot/data
    networks:
      - napcat-network

networks:
  napcat-network:
    name: napcat-network
    driver: bridge

volumes:
  astrbot-data:
    external: true
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;3.2 NapCat + AstrBot 一起部署（分开网络）&lt;/h2&gt;
&lt;p&gt;一份 Compose 里放两个服务，但网络分开。相比同一网络版本，多了 AstrBot 的 &lt;code&gt;6199&lt;/code&gt; 映射和 NapCat 的 &lt;code&gt;extra_hosts&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  astrbot:
    image: soulter/astrbot:latest
    container_name: astrbot
    restart: always
    security_opt:
      - no-new-privileges:true
    ports:
      - &quot;6185:6185&quot;
+      - &quot;6199:6199&quot;
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - astrbot-data:/AstrBot/data
      - /etc/localtime:/etc/localtime:ro
    networks:
      - astrbot-network

  napcat:
    image: mlikiowa/napcat-docker:latest
    container_name: napcat
    restart: always
    environment:
      - NAPCAT_UID=0
      - NAPCAT_GID=0
+    extra_hosts:
+      - &quot;host.docker.internal:host-gateway&quot;
    ports:
      - &quot;3000:3000&quot;
      - &quot;3001:3001&quot;
      - &quot;6099:6099&quot;
    volumes:
      - ./napcat/config:/app/napcat/config
      - ./ntqq:/app/.config/QQ
      - astrbot-data:/AstrBot/data
    networks:
      - napcat-network

networks:
  astrbot-network:
    name: astrbot-network
    driver: bridge
  napcat-network:
    name: napcat-network
    driver: bridge

volumes:
  astrbot-data:
    name: astrbot-data
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;3.3 SnowLuma 单独部署（snowluma-network）&lt;/h2&gt;
&lt;p&gt;AstrBot 已经部署好，只新增 SnowLuma：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  snowluma:
    image: ${SNOWLUMA_IMAGE:-motricseven7/snowluma:latest}
    container_name: ${SNOWLUMA_CONTAINER:-snowluma}
    restart: unless-stopped
    user: &quot;0:0&quot;
    shm_size: 1gb
    cap_add:
      - SYS_PTRACE
    security_opt:
      - seccomp=unconfined
+    extra_hosts:
+      - &quot;host.docker.internal:host-gateway&quot;
    environment:
      VNC_PASSWD: ${VNC_PASSWD:-vncpasswd}
      SNOWLUMA_UID: ${SNOWLUMA_UID:-1000}
      SNOWLUMA_GID: ${SNOWLUMA_GID:-1000}
      SNOWLUMA_WEBUI_PORT: ${SNOWLUMA_WEBUI_PORT:-5099}
      SNOWLUMA_LOG_LEVEL: ${SNOWLUMA_LOG_LEVEL:-info}
      SNOWLUMA_SCREEN: ${SNOWLUMA_SCREEN:-1920x1080x16}
      SNOWLUMA_HOOK_AUTOLOAD: ${SNOWLUMA_HOOK_AUTOLOAD:-1}
      SNOWLUMA_EXTRA_QQ_HOMES: &quot;${SNOWLUMA_EXTRA_QQ_HOMES:-}&quot;
      SNOWLUMA_QQ_FLAGS: &quot;${SNOWLUMA_QQ_FLAGS:---disable-gpu --disable-software-rasterizer --disable-gpu-compositing}&quot;
    ports:
      - &quot;${VNC_PORT:-5900}:5900&quot;
      - &quot;${NOVNC_PORT:-6081}:6081&quot;
      - &quot;${SNOWLUMA_WEBUI_HOST_PORT:-5099}:${SNOWLUMA_WEBUI_PORT:-5099}&quot;
      - &quot;${ONEBOT_HTTP_PORT:-3000}:3000&quot;
      - &quot;${ONEBOT_WS_PORT:-3001}:3001&quot;
    volumes:
      - snowluma-data:/app/snowluma-data
      - snowluma-qq-config:/app/.config
      - snowluma-qq-data:/app/.local/share
      - astrbot-data:/AstrBot/data
    networks:
      - snowluma-network

networks:
  snowluma-network:
    name: snowluma-network
    driver: bridge

volumes:
  snowluma-data:
  snowluma-qq-config:
  snowluma-qq-data:
  astrbot-data:
    external: true
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;3.4 SnowLuma + AstrBot 一起部署（分开网络）&lt;/h2&gt;
&lt;p&gt;一份 Compose 里放两个服务，网络分开。相比同一网络版本，多了 AstrBot 的 &lt;code&gt;6199&lt;/code&gt; 映射和 SnowLuma 的 &lt;code&gt;extra_hosts&lt;/code&gt;：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  astrbot:
    image: soulter/astrbot:latest
    container_name: astrbot
    restart: always
    security_opt:
      - no-new-privileges:true
    ports:
      - &quot;6185:6185&quot;
+      - &quot;6199:6199&quot;
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - astrbot-data:/AstrBot/data
      - /etc/localtime:/etc/localtime:ro
    networks:
      - astrbot-network

  snowluma:
    image: ${SNOWLUMA_IMAGE:-motricseven7/snowluma:latest}
    container_name: ${SNOWLUMA_CONTAINER:-snowluma}
    restart: unless-stopped
    user: &quot;0:0&quot;
    shm_size: 1gb
    cap_add:
      - SYS_PTRACE
    security_opt:
      - seccomp=unconfined
+    extra_hosts:
+      - &quot;host.docker.internal:host-gateway&quot;
    environment:
      VNC_PASSWD: ${VNC_PASSWD:-vncpasswd}
      SNOWLUMA_UID: ${SNOWLUMA_UID:-1000}
      SNOWLUMA_GID: ${SNOWLUMA_GID:-1000}
      SNOWLUMA_WEBUI_PORT: ${SNOWLUMA_WEBUI_PORT:-5099}
      SNOWLUMA_LOG_LEVEL: ${SNOWLUMA_LOG_LEVEL:-info}
      SNOWLUMA_SCREEN: ${SNOWLUMA_SCREEN:-1920x1080x16}
      SNOWLUMA_HOOK_AUTOLOAD: ${SNOWLUMA_HOOK_AUTOLOAD:-1}
      SNOWLUMA_EXTRA_QQ_HOMES: &quot;${SNOWLUMA_EXTRA_QQ_HOMES:-}&quot;
      SNOWLUMA_QQ_FLAGS: &quot;${SNOWLUMA_QQ_FLAGS:---disable-gpu --disable-software-rasterizer --disable-gpu-compositing}&quot;
    ports:
      - &quot;${VNC_PORT:-5900}:5900&quot;
      - &quot;${NOVNC_PORT:-6081}:6081&quot;
      - &quot;${SNOWLUMA_WEBUI_HOST_PORT:-5099}:${SNOWLUMA_WEBUI_PORT:-5099}&quot;
      - &quot;${ONEBOT_HTTP_PORT:-3000}:3000&quot;
      - &quot;${ONEBOT_WS_PORT:-3001}:3001&quot;
    volumes:
      - snowluma-data:/app/snowluma-data
      - snowluma-qq-config:/app/.config
      - snowluma-qq-data:/app/.local/share
      - astrbot-data:/AstrBot/data
    networks:
      - snowluma-network

networks:
  astrbot-network:
    name: astrbot-network
    driver: bridge
  snowluma-network:
    name: snowluma-network
    driver: bridge

volumes:
  snowluma-data:
  snowluma-qq-config:
  snowluma-qq-data:
  astrbot-data:
    name: astrbot-data
&lt;/code&gt;&lt;/pre&gt;
&lt;h1&gt;4. 填写 WebSocket URL&lt;/h1&gt;
&lt;p&gt;NapCat 在「网络配置 → 新建 → Websocket客户端」里填：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ws://host.docker.internal:6199/ws
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/adapter/napcat/ws-cross-network.png&quot; alt=&quot;跨网络下填写 ws://host.docker.internal:6199/ws w-100%&quot; title=&quot;名称 astrbot，URL ws://host.docker.internal:6199/ws，Token 留空&quot; /&gt;&lt;/p&gt;
&lt;p&gt;Windows 上的 NapCat 没有 Docker 网络，直接填服务器地址：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ws://&amp;lt;服务器IP&amp;gt;:6199/ws
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;如果 AstrBot 在本机 Docker Desktop，则填 &lt;code&gt;ws://127.0.0.1:6199/ws&lt;/code&gt;。&lt;/p&gt;
&lt;h1&gt;5. 验证&lt;/h1&gt;
&lt;p&gt;客户端日志出现反向 WebSocket 已启动，AstrBot 日志出现：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;aiocqhttp(OneBot v11) 适配器已连接。
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;就说明跨网络连接成功。NapCat/SnowLuma 的完整验证步骤见：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/posts/deploy/astrbot-adapter-napcat/&quot;&gt;NapCat 接入&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/posts/deploy/astrbot-adapter-snowluma/&quot;&gt;SnowLuma 接入&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;h1&gt;常见问题&lt;/h1&gt;
&lt;p&gt;::: collapse&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;客户端一直连接失败&lt;/p&gt;
&lt;p&gt;确认 AstrBot 的 &lt;code&gt;6199&lt;/code&gt; 已映射到宿主机，并且防火墙/安全组放行的来源包含客户端 IP。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;Docker 客户端提示 &lt;code&gt;host.docker.internal&lt;/code&gt; 解析失败&lt;/p&gt;
&lt;p&gt;给客户端容器加 &lt;code&gt;extra_hosts: host.docker.internal:host-gateway&lt;/code&gt;，或者在 1Panel 的主机映射里添加同样的记录。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;Windows 上 NapCat 连不上&lt;/p&gt;
&lt;p&gt;先用 &lt;code&gt;telnet &amp;lt;服务器IP&amp;gt; 6199&lt;/code&gt; 或 &lt;code&gt;Test-NetConnection &amp;lt;服务器IP&amp;gt; -Port 6199&lt;/code&gt; 确认端口可达。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;6199 要不要开放到公网&lt;/p&gt;
&lt;p&gt;不要。只放行客户端所在 IP；同网络部署不需要映射。&lt;/p&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;:::&lt;/p&gt;
</content:encoded></item><item><title>AstrBot 接入 QQ：NapCat（OneBot v11）</title><link>https://blog.0v0.uno/posts/deploy/astrbot-adapter-napcat/</link><guid isPermaLink="true">https://blog.0v0.uno/posts/deploy/astrbot-adapter-napcat/</guid><description>NapCat 通过 OneBot v11 接入 AstrBot：Windows / Linux Docker 部署、网络选择和 WebSocket 配置。</description><pubDate>Sun, 15 Nov 2026 07:43:11 GMT</pubDate><content:encoded>&lt;p&gt;NapCat 通过 &lt;strong&gt;OneBot v11&lt;/strong&gt; 接入 AstrBot。顺序是先在 AstrBot 里创建适配器，再部署 NapCat，最后在 NapCat 里填 WebSocket 地址。&lt;/p&gt;
&lt;p&gt;:::info[和 SnowLuma 二选一]
NapCat 和 &lt;a href=&quot;/posts/deploy/astrbot-adapter-snowluma/&quot;&gt;SnowLuma&lt;/a&gt; 共用同一个 OneBot v11 适配器，选一个接入即可；两个客户端同时连同一个 &lt;code&gt;6199&lt;/code&gt; 会冲突。
:::&lt;/p&gt;
&lt;h1&gt;1. 在 AstrBot 中创建 OneBot v11 适配器&lt;/h1&gt;
&lt;p&gt;打开 AstrBot WebUI，进入「机器人 → 创建机器人」：&lt;/p&gt;
&lt;p&gt;:::steps[创建适配器]&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;创建机器人&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;消息平台类别选 &lt;code&gt;OneBot v11&lt;/code&gt;，机器人名称填 &lt;code&gt;qq&lt;/code&gt;。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;填写反向 WebSocket&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;反向 WebSocket 主机填 &lt;code&gt;0.0.0.0&lt;/code&gt;，端口填 &lt;code&gt;6199&lt;/code&gt;，Token 留空。&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/adapter/napcat/astrbot-create-onebot.png&quot; alt=&quot;AstrBot 创建 OneBot v11 机器人 w-100%&quot; title=&quot;消息平台类别 OneBot v11，反向 WebSocket 主机 0.0.0.0，端口 6199&quot; /&gt;&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;保存并启用&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;保存后回到机器人列表，确认 &lt;code&gt;qq&lt;/code&gt; 处于运行中。NapCat 后面连的就是这个 &lt;code&gt;6199&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/adapter/napcat/astrbot-bot-page.png&quot; alt=&quot;AstrBot 机器人列表 w-100%&quot; title=&quot;qq 使用 aiocqhttp，反向 WebSocket 端口 6199&quot; /&gt;
:::&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;h1&gt;2. 部署 NapCat&lt;/h1&gt;
&lt;p&gt;:::warning[NapCat 和 Desktop 都已删库]
NapCat 和 NapCatQQ-Desktop 的仓库都已被删除，下面的包名和下载入口仅作历史参考；找不到时使用你本地备份的安装包。
:::&lt;/p&gt;
&lt;p&gt;:::info[端口]
AstrBot WebUI &lt;code&gt;6185&lt;/code&gt;，NapCat WebUI &lt;code&gt;6099&lt;/code&gt;。&lt;code&gt;6199&lt;/code&gt; 只在跨网络时需要，同一网络不需要暴露；跨网络见 &lt;a href=&quot;/posts/deploy/astrbot-adapter-different-network/&quot;&gt;不同网络下的 OneBot WebSocket 通信&lt;/a&gt;。
:::&lt;/p&gt;
&lt;h2&gt;2.1 Windows 部署&lt;/h2&gt;
&lt;p&gt;Windows 上不只有一个包，先按用途选：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;包 / 工具&lt;/th&gt;
&lt;th&gt;运行方式&lt;/th&gt;
&lt;th&gt;需要预装&lt;/th&gt;
&lt;th&gt;和日常 QQ 的关系&lt;/th&gt;
&lt;th&gt;适合&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;NapCat.Framework&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;以插件/注入方式挂到已安装的 QQNT&lt;/td&gt;
&lt;td&gt;QQNT&lt;/td&gt;
&lt;td&gt;共用桌面 QQ 的登录态&lt;/td&gt;
&lt;td&gt;已经有桌面 QQ，想直接复用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;NapCat.Shell&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;独立无头进程&lt;/td&gt;
&lt;td&gt;自己装 QQ + Node.js&lt;/td&gt;
&lt;td&gt;独立&lt;/td&gt;
&lt;td&gt;Linux/Docker、手动部署&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;NapCat.Shell.Windows.Node&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;自带 QQ + 便携 Node 的整合包&lt;/td&gt;
&lt;td&gt;无&lt;/td&gt;
&lt;td&gt;独立于日常 QQ&lt;/td&gt;
&lt;td&gt;Windows 想解压即用&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;NapCat.Shell.Windows.OneKey&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;一键安装器，生成 &lt;code&gt;NapCat.XXXX.Shell&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;无，安装器会准备&lt;/td&gt;
&lt;td&gt;取决于版本，可能和桌面 QQ 共用&lt;/td&gt;
&lt;td&gt;Windows 想按向导安装&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;NapCatQQ Desktop&lt;/td&gt;
&lt;td&gt;单 EXE 图形管理器&lt;/td&gt;
&lt;td&gt;由工具引导安装&lt;/td&gt;
&lt;td&gt;取决于底层 NapCat&lt;/td&gt;
&lt;td&gt;Windows 桌面用户，推荐&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h3&gt;方式一：Windows OneKey&lt;/h3&gt;
&lt;p&gt;:::steps[Windows OneKey 启动]&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;下载并解压&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;下载 &lt;code&gt;NapCat.Shell.Windows.OneKey.zip&lt;/code&gt;，解压到普通目录，不要放 &lt;code&gt;Program Files&lt;/code&gt; 或需要管理员权限的路径。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;运行安装器&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;双击 &lt;code&gt;NapCatInstaller.exe&lt;/code&gt;，等待它生成 &lt;code&gt;NapCat.XXXX.Shell&lt;/code&gt; 文件夹。首次运行需要联网准备文件。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;启动 NapCat&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;进入 &lt;code&gt;NapCat.XXXX.Shell&lt;/code&gt;，双击 &lt;code&gt;napcat.bat&lt;/code&gt;。控制台会打印 WebUI Token。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;登录 WebUI 和 QQ&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;浏览器打开 &lt;code&gt;http://127.0.0.1:6099&lt;/code&gt;，用日志里的 Token 登录，扫码登录 QQ。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;下一步&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;Windows 上的 NapCat 和 AstrBot 通常不在同一 Docker 网络，WebSocket 地址见 &lt;a href=&quot;/posts/deploy/astrbot-adapter-different-network/&quot;&gt;不同网络下的 OneBot WebSocket 通信&lt;/a&gt;。
:::&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;:::tip[不想用安装器]
如果 OneKey 安装器下载失败，可以试 &lt;code&gt;NapCat.Shell.Windows.Node.zip&lt;/code&gt;：自带 QQ 和便携 Node，解压后直接运行 &lt;code&gt;napcat.bat&lt;/code&gt;，不依赖系统安装的 QQ/Node。
:::&lt;/p&gt;
&lt;h3&gt;方式二：NapCatQQ Desktop（推荐）&lt;/h3&gt;
&lt;p&gt;:::steps[NapCatQQ Desktop]&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;下载单文件工具&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;下载 &lt;code&gt;NapCatQQ-Desktop&lt;/code&gt; 的 EXE。它不依赖额外运行库，双击即可打开。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;按引导准备环境&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;在工具里按引导安装或选择 QQ 与 NapCat；它会自动检测环境并给出安装入口。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;启动账号&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;新建或选择账号，启动 NapCat，扫码登录 QQ。托盘可以后台托管，多账号在左侧切换。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;下一步&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;Windows 上的 NapCat 和 AstrBot 通常不在同一 Docker 网络，WebSocket 地址见 &lt;a href=&quot;/posts/deploy/astrbot-adapter-different-network/&quot;&gt;不同网络下的 OneBot WebSocket 通信&lt;/a&gt;。
:::&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;:::tip[为什么推荐 Desktop]
单 EXE、图形界面、多账号、自动更新、托盘托管；比手动跑 &lt;code&gt;napcat.bat&lt;/code&gt; 少踩路径和环境坑。
:::&lt;/p&gt;
&lt;h2&gt;2.2 Linux Docker 部署&lt;/h2&gt;
&lt;h3&gt;方式一：1Panel 容器部署&lt;/h3&gt;
&lt;p&gt;:::steps[创建 NapCat 容器]&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;基本信息&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;1Panel 里进入「容器 → 创建容器」，镜像填 &lt;code&gt;mlikiowa/napcat-docker:latest&lt;/code&gt;，名称填 &lt;code&gt;napcat&lt;/code&gt;，重启策略选 &lt;code&gt;always&lt;/code&gt;。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;端口&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;映射 &lt;code&gt;6099&lt;/code&gt; 给 NapCat WebUI。&lt;code&gt;3000/3001&lt;/code&gt; 是 OneBot HTTP/WS 服务，用反向 WS 接入 AstrBot 时可以不映射。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;环境变量&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;NAPCAT_UID=0
NAPCAT_GID=0
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;如果服务器用非 root 用户运行 Docker，把 &lt;code&gt;0&lt;/code&gt; 换成 &lt;code&gt;id -u&lt;/code&gt; / &lt;code&gt;id -g&lt;/code&gt; 的实际值。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;挂载&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;/opt/astrbot/napcat/config&lt;/code&gt; → &lt;code&gt;/app/napcat/config&lt;/code&gt;：NapCat 配置&lt;/li&gt;
&lt;li&gt;&lt;code&gt;/opt/astrbot/ntqq&lt;/code&gt; → &lt;code&gt;/app/.config/QQ&lt;/code&gt;：QQ 数据&lt;/li&gt;
&lt;li&gt;&lt;code&gt;astrbot-data&lt;/code&gt; → &lt;code&gt;/AstrBot/data&lt;/code&gt;：共享 AstrBot 数据，发文件时才能读到
:::&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;在 NapCat 容器的「网络」里选择 AstrBot 容器所在的网络，例如 &lt;code&gt;astrbot_astrbot-network&lt;/code&gt;。同一网络不需要主机映射，也不用暴露 AstrBot 的 &lt;code&gt;6199&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/adapter/napcat/ip-same-network.png&quot; alt=&quot;同一网络下两个容器的 IP w-100%&quot; title=&quot;AstrBot 172.19.0.2，NapCat 172.19.0.3，说明在同一网络&quot; /&gt;&lt;/p&gt;
&lt;p&gt;:::tip[不同网络？]
NapCat 和 AstrBot 不在同一 Docker 网络时，见 &lt;a href=&quot;/posts/deploy/astrbot-adapter-different-network/&quot;&gt;不同网络下的 OneBot WebSocket 通信&lt;/a&gt;。
:::&lt;/p&gt;
&lt;p&gt;:::warning[网络名不要凭感觉填]
如果你按前面的文章用 &lt;code&gt;docker network create astrbot-network&lt;/code&gt; 创建过网络，AstrBot 却跑在 Compose 生成的 &lt;code&gt;astrbot_astrbot-network&lt;/code&gt; 上，NapCat 选错网络就会解析不到 &lt;code&gt;astrbot&lt;/code&gt;。以 AstrBot 容器「网络」页显示的网络名为准，不要只看 IP。
:::&lt;/p&gt;
&lt;h3&gt;方式二：Docker Compose 部署&lt;/h3&gt;
&lt;p&gt;:::steps[部署 NapCat]&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;保存 NapCat 配置&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;同一网络不需要改 AstrBot 的 &lt;code&gt;ports&lt;/code&gt;，&lt;code&gt;6199&lt;/code&gt; 只在容器网络内部使用。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  napcat:
    image: mlikiowa/napcat-docker:latest
    container_name: napcat
    restart: always
    environment:
      - NAPCAT_UID=0
      - NAPCAT_GID=0
    ports:
      - &quot;6099:6099&quot;
    volumes:
      - ./napcat/config:/app/napcat/config
      - ./ntqq:/app/.config/QQ
      - astrbot-data:/AstrBot/data
    networks:
      - astrbot-network

networks:
  astrbot-network:
    external: true
    name: astrbot_astrbot-network # 改成 AstrBot 实际使用的网络名

volumes:
  astrbot-data:
    external: true
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;保存为 &lt;code&gt;/opt/astrbot/compose.napcat.yml&lt;/code&gt;。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;启动&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;cd /opt/astrbot
docker compose -f compose.napcat.yml up -d
&lt;/code&gt;&lt;/pre&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;:::&lt;/p&gt;
&lt;p&gt;:::warning[网络名和卷名要对应]
&lt;code&gt;name&lt;/code&gt; 必须和 AstrBot 容器「网络」页显示的一致，常见的是 &lt;code&gt;astrbot_astrbot-network&lt;/code&gt;；手工创建过 &lt;code&gt;astrbot-network&lt;/code&gt; 就改成它。&lt;code&gt;astrbot-data&lt;/code&gt; 也必须是已存在的卷；如果 AstrBot 用的是 &lt;code&gt;./data&lt;/code&gt;，把挂载改成 &lt;code&gt;./data:/AstrBot/data&lt;/code&gt;，并删掉顶层 &lt;code&gt;volumes:&lt;/code&gt;。
:::&lt;/p&gt;
&lt;h3&gt;方式三：AstrBot + NapCat 一起部署&lt;/h3&gt;
&lt;p&gt;如果还没有单独部署 AstrBot，可以直接用一份 Compose 把两者一起拉起。两个容器都在 &lt;code&gt;astrbot-network&lt;/code&gt;，共享 &lt;code&gt;astrbot-data&lt;/code&gt;，&lt;code&gt;6199&lt;/code&gt; 不映射到宿主机。&lt;/p&gt;
&lt;p&gt;:::steps[一起部署]&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;保存配置&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  astrbot:
    image: soulter/astrbot:latest
    container_name: astrbot
    restart: always
    security_opt:
      - no-new-privileges:true
    ports:
      - &quot;6185:6185&quot; # AstrBot WebUI
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - astrbot-data:/AstrBot/data
      - /etc/localtime:/etc/localtime:ro
    networks:
      - astrbot-network

  napcat:
    image: mlikiowa/napcat-docker:latest
    container_name: napcat
    restart: always
    environment:
      - NAPCAT_UID=0
      - NAPCAT_GID=0
    ports:
      - &quot;3000:3000&quot;
      - &quot;3001:3001&quot;
      - &quot;6099:6099&quot; # NapCat WebUI
    volumes:
      - ./napcat/config:/app/napcat/config
      - ./ntqq:/app/.config/QQ
      - astrbot-data:/AstrBot/data
    networks:
      - astrbot-network

networks:
  astrbot-network:
    driver: bridge

volumes:
  astrbot-data:
    name: astrbot-data
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;保存为 &lt;code&gt;/opt/astrbot/compose.napcat.yml&lt;/code&gt;。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;启动&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;cd /opt/astrbot
docker compose -f compose.napcat.yml up -d
&lt;/code&gt;&lt;/pre&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;:::&lt;/p&gt;
&lt;p&gt;:::caution[只适用于同一网络]
这份配置依赖 &lt;code&gt;astrbot-network&lt;/code&gt; 内部解析。Windows 或跨网络部署见 &lt;a href=&quot;/posts/deploy/astrbot-adapter-different-network/&quot;&gt;不同网络下的 OneBot WebSocket 通信&lt;/a&gt;。
:::&lt;/p&gt;
&lt;h1&gt;3. 配置 NapCat WebSocket&lt;/h1&gt;
&lt;p&gt;NapCat 启动并登录 QQ 后，在 NapCat WebUI 里新建 WebSocket 客户端。同一网络填：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;ws://astrbot:6199/ws
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::tip[Windows 或跨网络？]
见 &lt;a href=&quot;/posts/deploy/astrbot-adapter-different-network/&quot;&gt;不同网络下的 OneBot WebSocket 通信&lt;/a&gt;。
:::&lt;/p&gt;
&lt;p&gt;:::steps[添加 WebSocket 客户端]&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;新建客户端&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;打开 NapCat WebUI，进入「网络配置 → 新建 → Websocket客户端」。&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/adapter/napcat/ws-menu.png&quot; alt=&quot;NapCat 新建 WebSocket 客户端 w-100%&quot; title=&quot;在网络配置里新建 Websocket客户端&quot; /&gt;&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;填写名称和 URL&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;名称填 &lt;code&gt;astrbot&lt;/code&gt;，URL 填 &lt;code&gt;ws://astrbot:6199/ws&lt;/code&gt;，Token 留空。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;保存并启用&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;保存后确认客户端处于启用状态。
:::&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;同一网络的填写示例：&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/adapter/napcat/ws-same-network.png&quot; alt=&quot;同一网络下填写 ws://astrbot:6199/ws w-100%&quot; title=&quot;名称 astrbot，URL ws://astrbot:6199/ws，Token 留空&quot; /&gt;&lt;/p&gt;
&lt;h1&gt;4. 登录 NapCat&lt;/h1&gt;
&lt;p&gt;:::steps[登录 NapCat]&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;获取 Token&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;浏览器打开 &lt;code&gt;http://&amp;lt;服务器IP&amp;gt;:6099/webui&lt;/code&gt;。登录用的 Token 在容器日志里：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker logs napcat 2&amp;gt;&amp;amp;1 | grep -i -E &quot;webui|token&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;也可以到挂载出来的 &lt;code&gt;./napcat/config/webui.json&lt;/code&gt; 里找 &lt;code&gt;token&lt;/code&gt; 字段。&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/verify/napcat-webui-token.png&quot; alt=&quot;1Panel 中 NapCat 日志里的 WebUi Token 和访问地址 w-100%&quot; title=&quot;红框中是带 token 的 WebUI 地址，token 就是登录凭证&quot; /&gt;&lt;/p&gt;
&lt;p&gt;截图中的 Token 仅作示例，请以自己日志里的值为准。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;登录 WebUI&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;把日志里的 Token 填进 WebUI：&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/verify/napcat-webui-login.png&quot; alt=&quot;NapCat Web Login 输入 Token w-100%&quot; title=&quot;在 Token 输入框填入日志里的 WebUi Token&quot; /&gt;&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;扫码登录 QQ&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;如果 QQ 还没登录，NapCat 会要求扫码：&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/verify/napcat-qq-qr.png&quot; alt=&quot;NapCat 扫码登录 QQ w-100%&quot; title=&quot;用手机 QQ 扫描二维码完成登录&quot; /&gt;&lt;/p&gt;
&lt;p&gt;登录成功后进入 NapCat 面板：&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/verify/napcat-dashboard.png&quot; alt=&quot;NapCat 面板首页 w-100%&quot; title=&quot;在基础信息里确认 NapCat 版本、QQ 版本和运行状态&quot; /&gt;
:::&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;h1&gt;5. 验证连接&lt;/h1&gt;
&lt;p&gt;:::steps[验证连接]&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;看 NapCat 日志&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;日志里出现反向 WebSocket 已启动，说明客户端在尝试连接。&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/adapter/napcat/ws-connected-log.png&quot; alt=&quot;NapCat 日志中的反向 WebSocket 服务 w-100%&quot; title=&quot;日志里能看到 WebSocket 反向服务已启动&quot; /&gt;&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;看 AstrBot 日志&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;出现下面这行，说明连接成功：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;aiocqhttp(OneBot v11) 适配器已连接。
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/verify/astrbot-adapter-connected.png&quot; alt=&quot;AstrBot 日志显示适配器已连接 w-100%&quot; title=&quot;看到 aiocqhttp(OneBot v11) 适配器已连接即可&quot; /&gt;&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;发一条测试消息&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;在 QQ 里私聊机器人发一条消息，AstrBot 日志出现 &lt;code&gt;收到 ... 测试&lt;/code&gt;，说明消息已经从 NapCat 送到 AstrBot：&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/adapter/napcat/test-message-no-model.png&quot; alt=&quot;AstrBot 日志显示收到测试消息 w-100%&quot; title=&quot;日志里出现「收到 ... 测试」，说明消息发送成功&quot; /&gt;&lt;/p&gt;
&lt;p&gt;如果下面还提示 &lt;code&gt;未找到任何对话模型（提供商）&lt;/code&gt;，只说明还没配置模型，不影响这次连接验证；配置好模型后再发消息就能收到回复。
:::&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;h1&gt;常见问题&lt;/h1&gt;
&lt;p&gt;::: collapse&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;NapCat 日志一直提示连接失败&lt;/p&gt;
&lt;p&gt;检查两个容器是不是在同一个网络，URL 里的 &lt;code&gt;astrbot&lt;/code&gt; 必须能解析成 AstrBot 容器。不在同一网络时见 &lt;a href=&quot;/posts/deploy/astrbot-adapter-different-network/&quot;&gt;不同网络下的 OneBot WebSocket 通信&lt;/a&gt;。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;AstrBot 和 NapCat 一起部署时出现 Network 错误&lt;/p&gt;
&lt;p&gt;检查 compose 里的网络名是否和 AstrBot 实际使用的网络一致；同一份 compose 里的两个服务必须加入同一个网络。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;AstrBot 提示 Token 不匹配&lt;/p&gt;
&lt;p&gt;AstrBot 的反向 WebSocket Token 和 NapCat 的 WebSocket 客户端 Token 必须一致；不想校验就两边都留空。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;NapCat 发文件时提示找不到文件&lt;/p&gt;
&lt;p&gt;AstrBot 和 NapCat 没有共享 &lt;code&gt;astrbot-data&lt;/code&gt;；两个容器都要把同一个卷挂到 &lt;code&gt;/AstrBot/data&lt;/code&gt;。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;6199 要不要开放到公网&lt;/p&gt;
&lt;p&gt;不要。同一网络不需要映射；跨网络的做法见 &lt;a href=&quot;/posts/deploy/astrbot-adapter-different-network/&quot;&gt;不同网络下的 OneBot WebSocket 通信&lt;/a&gt;，且只放行客户端 IP。&lt;/p&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;:::&lt;/p&gt;
</content:encoded></item><item><title>AstrBot 接入 QQ：SnowLuma（OneBot v11）</title><link>https://blog.0v0.uno/posts/deploy/astrbot-adapter-snowluma/</link><guid isPermaLink="true">https://blog.0v0.uno/posts/deploy/astrbot-adapter-snowluma/</guid><description>SnowLuma 通过 OneBot v11 接入 AstrBot：AstrBot 适配器创建、WebSocket 反向客户端配置和连接验证。</description><pubDate>Sun, 15 Nov 2026 07:43:11 GMT</pubDate><content:encoded>&lt;p&gt;SnowLuma 通过 &lt;strong&gt;OneBot v11&lt;/strong&gt; 接入 AstrBot。AstrBot 侧和 &lt;a href=&quot;/posts/deploy/astrbot-adapter-napcat/&quot;&gt;NapCat&lt;/a&gt; 共用同一个适配器；这篇从创建适配器开始写，单独看也能跑通。&lt;/p&gt;
&lt;p&gt;:::info[和 NapCat 二选一]
SnowLuma 和 NapCat 共用同一个 OneBot v11 适配器，选一个接入即可；两个客户端同时连同一个 &lt;code&gt;6199&lt;/code&gt; 会冲突。
:::&lt;/p&gt;
&lt;h1&gt;1. 在 AstrBot 中创建 OneBot v11 适配器&lt;/h1&gt;
&lt;p&gt;如果已经按 NapCat 那篇创建过适配器，直接跳到&lt;a href=&quot;#2-%E9%83%A8%E7%BD%B2-snowluma&quot;&gt;第 2 节&lt;/a&gt;。否则打开 AstrBot WebUI，进入「机器人 → 创建机器人」：&lt;/p&gt;
&lt;p&gt;:::steps[创建适配器]&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;创建机器人&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;消息平台类别选 &lt;code&gt;OneBot v11&lt;/code&gt;，机器人名称填 &lt;code&gt;qq&lt;/code&gt;。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;填写反向 WebSocket&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;反向 WebSocket 主机填 &lt;code&gt;0.0.0.0&lt;/code&gt;，端口填 &lt;code&gt;6199&lt;/code&gt;，Token 留空。&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/adapter/napcat/astrbot-create-onebot.png&quot; alt=&quot;AstrBot 创建 OneBot v11 机器人 w-100%&quot; title=&quot;消息平台类别 OneBot v11，反向 WebSocket 主机 0.0.0.0，端口 6199&quot; /&gt;&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;保存并启用&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;保存后回到机器人列表，确认 &lt;code&gt;qq&lt;/code&gt; 处于运行中。SnowLuma 后面连的就是这个 &lt;code&gt;6199&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/adapter/napcat/astrbot-bot-page.png&quot; alt=&quot;AstrBot 机器人列表 w-100%&quot; title=&quot;qq 使用 aiocqhttp，反向 WebSocket 端口 6199&quot; /&gt;
:::&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;h1&gt;2. 部署 SnowLuma&lt;/h1&gt;
&lt;p&gt;:::warning[SnowLuma 已删库]
SnowLuma 因法律问题已被删除仓库，下面的配置仅作历史参考。
:::&lt;/p&gt;
&lt;p&gt;:::info[端口]
AstrBot WebUI &lt;code&gt;6185&lt;/code&gt;；&lt;/p&gt;
&lt;p&gt;SnowLuma WebUI &lt;code&gt;5099&lt;/code&gt;；&lt;/p&gt;
&lt;p&gt;noVNC &lt;code&gt;6081&lt;/code&gt;；&lt;/p&gt;
&lt;p&gt;&lt;code&gt;5900&lt;/code&gt; 只有直连 VNC 时才需要。&lt;/p&gt;
&lt;p&gt;&lt;code&gt;6199&lt;/code&gt; 同网络不需要暴露；跨网络见 &lt;a href=&quot;/posts/deploy/astrbot-adapter-different-network/&quot;&gt;不同网络下的 OneBot WebSocket 通信&lt;/a&gt;。
:::&lt;/p&gt;
&lt;p&gt;以 SnowLuma 为例，1Panel 防火墙放行 &lt;code&gt;6185&lt;/code&gt;、&lt;code&gt;5099&lt;/code&gt;、&lt;code&gt;6081&lt;/code&gt; 即可：&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/1panel/1panel-firewall-snowluma.png&quot; alt=&quot;1Panel 防火墙放行 AstrBot、SnowLuma 和 noVNC 端口 w-100%&quot; title=&quot;放行 6185、6081、5099，协议 TCP，来源全部 IPv4 地址&quot; /&gt;&lt;/p&gt;
&lt;h2&gt;2.1 单独部署 SnowLuma&lt;/h2&gt;
&lt;p&gt;AstrBot 已经部署好时，只新增 SnowLuma。它使用自己的 &lt;code&gt;snowluma-network&lt;/code&gt;，通过 &lt;code&gt;host.docker.internal&lt;/code&gt; 访问宿主机上的 AstrBot，并共享 &lt;code&gt;astrbot-data&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;:::steps[单独部署 SnowLuma]&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;保存配置&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;SnowLuma 需要先设置 &lt;code&gt;VNC_PASSWD&lt;/code&gt;，例如 &lt;code&gt;VNC_PASSWD=passwd123&lt;/code&gt;。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  snowluma:
    image: ${SNOWLUMA_IMAGE:-motricseven7/snowluma:latest}
    container_name: ${SNOWLUMA_CONTAINER:-snowluma}
    restart: unless-stopped
    user: &quot;0:0&quot;
    shm_size: 1gb
    cap_add:
      - SYS_PTRACE
    security_opt:
      - seccomp=unconfined
    extra_hosts:
      - &quot;host.docker.internal:host-gateway&quot;
    environment:
      VNC_PASSWD: ${VNC_PASSWD:-vncpasswd}
      SNOWLUMA_UID: ${SNOWLUMA_UID:-1000}
      SNOWLUMA_GID: ${SNOWLUMA_GID:-1000}
      SNOWLUMA_WEBUI_PORT: ${SNOWLUMA_WEBUI_PORT:-5099}
      SNOWLUMA_LOG_LEVEL: ${SNOWLUMA_LOG_LEVEL:-info}
      SNOWLUMA_SCREEN: ${SNOWLUMA_SCREEN:-1920x1080x16}
      SNOWLUMA_HOOK_AUTOLOAD: ${SNOWLUMA_HOOK_AUTOLOAD:-1}
      SNOWLUMA_EXTRA_QQ_HOMES: &quot;${SNOWLUMA_EXTRA_QQ_HOMES:-}&quot;
      SNOWLUMA_QQ_FLAGS: &quot;${SNOWLUMA_QQ_FLAGS:---disable-gpu --disable-software-rasterizer --disable-gpu-compositing}&quot;
    ports:
      - &quot;${VNC_PORT:-5900}:5900&quot;
      - &quot;${NOVNC_PORT:-6081}:6081&quot;
      - &quot;${SNOWLUMA_WEBUI_HOST_PORT:-5099}:${SNOWLUMA_WEBUI_PORT:-5099}&quot;
      - &quot;${ONEBOT_HTTP_PORT:-3000}:3000&quot;
      - &quot;${ONEBOT_WS_PORT:-3001}:3001&quot;
    volumes:
      - snowluma-data:/app/snowluma-data
      - snowluma-qq-config:/app/.config
      - snowluma-qq-data:/app/.local/share
      - astrbot-data:/AstrBot/data
    networks:
      - snowluma-network

networks:
  snowluma-network:
    name: snowluma-network
    driver: bridge

volumes:
  snowluma-data:
  snowluma-qq-config:
  snowluma-qq-data:
  astrbot-data:
    external: true
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;保存为 &lt;code&gt;/opt/astrbot/compose.snowluma.yml&lt;/code&gt;。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;启动&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;cd /opt/astrbot
docker compose -f compose.snowluma.yml up -d
&lt;/code&gt;&lt;/pre&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;:::&lt;/p&gt;
&lt;p&gt;:::caution[单独部署的 WebSocket]
SnowLuma 使用 &lt;code&gt;snowluma-network&lt;/code&gt; 时，WebSocket 配置见 &lt;a href=&quot;/posts/deploy/astrbot-adapter-different-network/&quot;&gt;不同网络下的 OneBot WebSocket 通信&lt;/a&gt;。&lt;/p&gt;
&lt;p&gt;&lt;code&gt;astrbot-data&lt;/code&gt; 用 &lt;code&gt;external: true&lt;/code&gt;，要求 AstrBot 已经创建同名卷；如果 AstrBot 用的是 &lt;code&gt;./data&lt;/code&gt;，把挂载改成 &lt;code&gt;/opt/astrbot/data:/AstrBot/data&lt;/code&gt;，并删掉顶层 &lt;code&gt;volumes&lt;/code&gt; 里的 &lt;code&gt;astrbot-data&lt;/code&gt;。
:::&lt;/p&gt;
&lt;h2&gt;2.2 AstrBot + SnowLuma 一起部署&lt;/h2&gt;
&lt;p&gt;如果还没有单独部署 AstrBot，可以用一份 Compose 把两者一起拉起。两个容器都在 &lt;code&gt;astrbot-network&lt;/code&gt;，共享 &lt;code&gt;astrbot-data&lt;/code&gt;，&lt;code&gt;6199&lt;/code&gt; 不映射到宿主机。&lt;/p&gt;
&lt;p&gt;:::steps[一起部署]&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;保存配置&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;SnowLuma 需要先设置 &lt;code&gt;VNC_PASSWD&lt;/code&gt;，例如 &lt;code&gt;VNC_PASSWD=passwd123&lt;/code&gt;。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  astrbot:
    image: soulter/astrbot:latest
    container_name: astrbot
    restart: always
    security_opt:
      - no-new-privileges:true
    ports:
      - &quot;6185:6185&quot; # AstrBot WebUI
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - astrbot-data:/AstrBot/data
      - /etc/localtime:/etc/localtime:ro
    networks:
      - astrbot-network

  snowluma:
    image: ${SNOWLUMA_IMAGE:-motricseven7/snowluma:latest}
    container_name: ${SNOWLUMA_CONTAINER:-snowluma}
    restart: unless-stopped
    user: &quot;0:0&quot;
    shm_size: 1gb
    cap_add:
      - SYS_PTRACE
    security_opt:
      - seccomp=unconfined
    environment:
      - VNC_PASSWD=${VNC_PASSWD:-vncpasswd}
      - SNOWLUMA_UID=${SNOWLUMA_UID:-1000}
      - SNOWLUMA_GID=${SNOWLUMA_GID:-1000}
      - SNOWLUMA_WEBUI_PORT=${SNOWLUMA_WEBUI_PORT:-5099}
      - SNOWLUMA_LOG_LEVEL=${SNOWLUMA_LOG_LEVEL:-info}
      - SNOWLUMA_SCREEN=${SNOWLUMA_SCREEN:-1920x1080x16}
      - SNOWLUMA_HOOK_AUTOLOAD=${SNOWLUMA_HOOK_AUTOLOAD:-1}
    ports:
      - &quot;${VNC_PORT:-5900}:5900&quot;
      - &quot;${NOVNC_PORT:-6081}:6081&quot;
      - &quot;${SNOWLUMA_WEBUI_HOST_PORT:-5099}:${SNOWLUMA_WEBUI_PORT:-5099}&quot;
      - &quot;${ONEBOT_HTTP_PORT:-3000}:3000&quot;
      - &quot;${ONEBOT_WS_PORT:-3001}:3001&quot;
    volumes:
      - snowluma-data:/app/snowluma-data
      - snowluma-qq-config:/app/.config
      - snowluma-qq-data:/app/.local/share
      - astrbot-data:/AstrBot/data
    networks:
      - astrbot-network

networks:
  astrbot-network:
    driver: bridge

volumes:
  snowluma-data:
  snowluma-qq-config:
  snowluma-qq-data:
  astrbot-data:
    name: astrbot-data
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;保存为 &lt;code&gt;/opt/astrbot/compose.snowluma.yml&lt;/code&gt;。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;启动&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;cd /opt/astrbot
docker compose -f compose.snowluma.yml up -d
&lt;/code&gt;&lt;/pre&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;:::&lt;/p&gt;
&lt;p&gt;:::caution[只适用于同一网络]
这份配置依赖 &lt;code&gt;astrbot-network&lt;/code&gt; 内部解析。不在同一网络时见 &lt;a href=&quot;/posts/deploy/astrbot-adapter-different-network/&quot;&gt;不同网络下的 OneBot WebSocket 通信&lt;/a&gt;。
:::&lt;/p&gt;
&lt;h1&gt;3. 配置 SnowLuma WebSocket&lt;/h1&gt;
&lt;p&gt;打开 SnowLuma WebUI。&lt;/p&gt;
&lt;p&gt;:::steps[配置 SnowLuma WebSocket]&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;打开 WebSocket 反向客户端&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;进入「节点配置 → OneBot 协议端点 → WebSocket 反向客户端」。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;填写名称&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;名称填 &lt;code&gt;astrbot&lt;/code&gt;。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;填写 URL&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;URL 填 &lt;code&gt;ws://astrbot:6199/ws&lt;/code&gt;，Token 留空。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;保存并启用&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;保存后确认客户端处于启用状态。
:::&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/verify/snowluma-websocket-client.png&quot; alt=&quot;一起部署的填写示例：ws://astrbot:6199/ws w-100%&quot; title=&quot;名称 astrbot，URL ws://astrbot:6199/ws&quot; /&gt;&lt;/p&gt;
&lt;p&gt;:::tip[不同网络？]
单独部署或跨网络时，见 &lt;a href=&quot;/posts/deploy/astrbot-adapter-different-network/&quot;&gt;不同网络下的 OneBot WebSocket 通信&lt;/a&gt;。
:::&lt;/p&gt;
&lt;h1&gt;4. 登录 SnowLuma&lt;/h1&gt;
&lt;p&gt;:::steps[登录 SnowLuma]&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;获取访问令牌&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;浏览器打开 &lt;code&gt;http://&amp;lt;服务器IP&amp;gt;:5099&lt;/code&gt;。首次登录需要访问令牌，令牌在容器日志里：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker logs snowluma 2&amp;gt;&amp;amp;1 | grep -i -E &quot;webui|token|凭证|访问令牌&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;日志里会打印 WebUI 的访问令牌，不同镜像版本的字段名可能不一样。把它填到登录页：&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/verify/snowluma-login.png&quot; alt=&quot;SnowLuma WebUI 登录页 w-100%&quot; title=&quot;在「输入访问令牌」处填入日志里的 Token&quot; /&gt;&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;同意用户协议&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;首次进入会显示 EULA，勾选「我已阅读并同意」后点「同意并继续」。&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/verify/snowluma-eula.png&quot; alt=&quot;SnowLuma 首次使用协议 w-100%&quot; title=&quot;勾选同意 EULA 后继续&quot; /&gt;&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;设置访问密码&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;按提示设置新的访问密码并确认。&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/verify/snowluma-set-password.png&quot; alt=&quot;SnowLuma 设置访问密码 w-100%&quot; title=&quot;设置并确认新的访问密码&quot; /&gt;&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;进入控制台并加载 QQ&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;设置完成后进入「概览」页；如果 QQ 还没启动，在「进程注入」里加载它，确认状态为「等待登录」。&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/verify/snowluma-overview.png&quot; alt=&quot;SnowLuma 控制台概览 w-100%&quot; title=&quot;在概览页确认服务状态&quot; /&gt;&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/verify/snowluma-process-injection.png&quot; alt=&quot;SnowLuma 进程注入等待登录 w-100%&quot; title=&quot;进程注入里显示 qq 等待登录&quot; /&gt;&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;登录 noVNC&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;浏览器打开 &lt;code&gt;http://&amp;lt;服务器IP&amp;gt;:6081&lt;/code&gt;，输入 VNC 密码后就能看到 SnowLuma 的桌面，容器会自动启动 QQ。&lt;/p&gt;
&lt;p&gt;VNC 密码来自 compose 里的 &lt;code&gt;VNC_PASSWD&lt;/code&gt;；没有改过时默认是 &lt;code&gt;vncpasswd&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/verify/snowluma-novnc-credential.webp&quot; alt=&quot;noVNC 登录凭证输入框 w-100%&quot; title=&quot;输入 VNC_PASSWD，点击发送凭证&quot; /&gt;&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;扫码登录 QQ&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;在桌面里用手机 QQ 扫码登录：&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/verify/snowluma-novnc-qq.png&quot; alt=&quot;SnowLuma noVNC 中扫码登录 QQ w-100%&quot; title=&quot;用手机 QQ 扫描 noVNC 桌面里的二维码&quot; /&gt;&lt;/p&gt;
&lt;p&gt;登录成功后，回到控制台的「进程注入」，可以看到 QQ 已在线：&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/verify/snowluma-qq-online.png&quot; alt=&quot;SnowLuma 进程注入显示 QQ 在线 w-100%&quot; title=&quot;进程注入里显示 QQ 已在线&quot; /&gt;
:::&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;:::caution[VNC 和 noVNC 不要裸奔]
6081（noVNC）和 5900（VNC 客户端）都能直接操作容器桌面，等于拿到 QQ 的控制权。只给自己使用的 IP 放行，不要把 5900 直接暴露到公网。
:::&lt;/p&gt;
&lt;h1&gt;5. 验证连接&lt;/h1&gt;
&lt;p&gt;:::steps[验证连接]&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;看 SnowLuma 概览&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;「OneBot 连接」里出现 &lt;code&gt;astrbot&lt;/code&gt; 的 WS 客户端「已连接」。&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/verify/snowluma-overview-connected.png&quot; alt=&quot;SnowLuma 概览页显示 astrbot 已连接 w-100%&quot; title=&quot;在线账号 1，astrbot WS 客户端已连接&quot; /&gt;&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;看 AstrBot 日志&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;日志里出现 &lt;code&gt;aiocqhttp(OneBot v11) 适配器已连接。&lt;/code&gt;&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/verify/snowluma-astrbot-adapter-connected.png&quot; alt=&quot;AstrBot 日志显示 SnowLuma 适配器已连接 w-100%&quot; title=&quot;aiocqhttp(OneBot v11) 适配器已连接&quot; /&gt;
:::&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;h1&gt;常见问题&lt;/h1&gt;
&lt;p&gt;::: collapse&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;SnowLuma 的 WS 客户端一直显示未连接&lt;/p&gt;
&lt;p&gt;&lt;a href=&quot;#22-astrbot--snowluma-%E4%B8%80%E8%B5%B7%E9%83%A8%E7%BD%B2&quot;&gt;2.2 一起部署&lt;/a&gt;：确认两个容器在同一个 Docker 网络，URL 里的 &lt;code&gt;astrbot&lt;/code&gt; 能解析到 AstrBot 容器。&lt;/p&gt;
&lt;p&gt;单独部署或跨网络：见 &lt;a href=&quot;/posts/deploy/astrbot-adapter-different-network/&quot;&gt;不同网络下的 OneBot WebSocket 通信&lt;/a&gt;。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;AstrBot 和 SnowLuma 一起部署时出现 Network 错误&lt;/p&gt;
&lt;p&gt;检查 compose 里的网络名是否和 AstrBot 实际使用的网络一致；同一份 compose 里的两个服务必须加入同一个网络。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;AstrBot 提示 Token 不匹配&lt;/p&gt;
&lt;p&gt;AstrBot 的反向 WebSocket Token 和 SnowLuma 的 Token 必须一致；不想校验就两边都留空。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;SnowLuma 的 VNC 密码在哪里设置&lt;/p&gt;
&lt;p&gt;在 &lt;a href=&quot;#21-%E5%8D%95%E7%8B%AC%E9%83%A8%E7%BD%B2-snowluma&quot;&gt;2.1 单独部署&lt;/a&gt; / &lt;a href=&quot;#22-astrbot--snowluma-%E4%B8%80%E8%B5%B7%E9%83%A8%E7%BD%B2&quot;&gt;2.2 AstrBot + SnowLuma 一起部署&lt;/a&gt; 的 Compose 环境变量里设置 &lt;code&gt;VNC_PASSWD&lt;/code&gt;。&lt;/p&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;:::&lt;/p&gt;
</content:encoded></item><item><title>AstrBot 在 Linux 上部署</title><link>https://blog.0v0.uno/posts/deploy/astrbot-linux/</link><guid isPermaLink="true">https://blog.0v0.uno/posts/deploy/astrbot-linux/</guid><description>使用 Docker 在 1panel 上部署 AstrBot</description><pubDate>Fri, 13 Nov 2026 15:10:45 GMT</pubDate><content:encoded>&lt;p&gt;AstrBot 是一个开源的一站式 Agentic 个人和群聊助手，可在 QQ、Telegram、企业微信、飞书、钉钉、Slack 等数十款主流即时通讯软件上部署&lt;/p&gt;
&lt;p&gt;这篇假设你已经有一台 Linux 服务器，并且装好了 1Panel 和 Docker。如果还没有，先看系列的前两篇: &lt;a href=&quot;/posts/deploy/server/&quot;&gt;Linux 海外服务器购买&lt;/a&gt; 和 &lt;a href=&quot;/posts/deploy/1panel/&quot;&gt;1panel安装&lt;/a&gt;.&lt;/p&gt;
&lt;h1&gt;安装前检查&lt;/h1&gt;
&lt;h2&gt;查看端口&lt;/h2&gt;
&lt;p&gt;部署前先确认端口。1Panel 防火墙和云厂商安全组是两层，==任意一层没放行，浏览器都打不开=={.error}。下面这些端口统一使用 &lt;code&gt;TCP&lt;/code&gt;：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;端口&lt;/th&gt;
&lt;th&gt;用途&lt;/th&gt;
&lt;th&gt;何时开放&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;6185&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;AstrBot WebUI&lt;/td&gt;
&lt;td&gt;必开，用于浏览器访问 AstrBot 后台&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;在 1Panel 中进入「主机 → 防火墙」，点击「创建」，类型选「自定义」，协议选 &lt;code&gt;TCP&lt;/code&gt;，端口填 &lt;code&gt;6185&lt;/code&gt;。来源尽量限制为自己的 IP，备注写清楚用途。&lt;/p&gt;
&lt;p&gt;:::tip[云厂商防火墙]
注意是在你购买服务器的地方放行端口
:::&lt;/p&gt;
&lt;h1&gt;在 1panel 中可视化安装&lt;/h1&gt;
&lt;p&gt;:::info
没有安装 1panel 请先安装 &lt;a href=&quot;/posts/deploy/1panel/&quot;&gt;1panel&lt;/a&gt;.&lt;/p&gt;
&lt;p&gt;下面的两种安装方式, &lt;strong&gt;选择一种&lt;/strong&gt;即可
:::&lt;/p&gt;
&lt;h2&gt;单独安装 Astrbot 容器&lt;/h2&gt;
&lt;p&gt;只跑一个 AstrBot 容器时，不需要写 Compose。按 ==网络 → 存储卷 → 容器=={.primary} 的顺序建三样东西即可。&lt;/p&gt;
&lt;p&gt;先按网络环境选镜像地址：&lt;/p&gt;
&lt;p&gt;:::tabs&lt;/p&gt;
&lt;p&gt;@tab 国内&lt;/p&gt;
&lt;p&gt;&lt;code&gt;m.daocloud.io/docker.io/soulter/astrbot:latest&lt;/code&gt;&lt;/p&gt;
&lt;p&gt;@tab 国外&lt;/p&gt;
&lt;p&gt;&lt;code&gt;soulter/astrbot:latest&lt;/code&gt;&lt;/p&gt;
&lt;p&gt;:::&lt;/p&gt;
&lt;p&gt;:::steps[单独安装 AstrBot 容器]&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;创建网络&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;在左侧进入「容器」，切到顶部的「网络」，点击「创建」。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;配置项&lt;/th&gt;
&lt;th&gt;填写&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;名称&lt;/td&gt;
&lt;td&gt;&lt;code&gt;astrbot-network&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;模式&lt;/td&gt;
&lt;td&gt;&lt;code&gt;bridge&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;子网&lt;/td&gt;
&lt;td&gt;&lt;code&gt;172.19.0.0/16&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;网关&lt;/td&gt;
&lt;td&gt;&lt;code&gt;172.19.0.1&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;IPv6&lt;/td&gt;
&lt;td&gt;关闭&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&lt;code&gt;172.17.0.0/16&lt;/code&gt; 是 Docker 默认 bridge，&lt;code&gt;172.18.0.0/16&lt;/code&gt; 是 1Panel 自带的 &lt;code&gt;1panel-network&lt;/code&gt;，所以这里用 ==&lt;code&gt;172.19.0.0/16&lt;/code&gt;=={.primary}，不要和宿主机局域网、VPN 或其他 Docker 网络重叠。只跑 AstrBot 和几个适配器，用 &lt;code&gt;/24&lt;/code&gt; 也够。&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/1panel/1panel-network-create.png&quot; alt=&quot;1Panel 创建 astrbot-network 网络 w-100%&quot; title=&quot;名称 astrbot-network，模式 bridge，子网 172.19.0.0/16，网关 172.19.0.1&quot; /&gt;&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;创建存储卷&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;切到顶部的「存储卷」，点击「创建」，名称填 ==&lt;code&gt;astrbot-data&lt;/code&gt;=={.primary}。&lt;/p&gt;
&lt;p&gt;命名卷由 Docker 管理，删除容器不会丢数据，权限问题也少；本机目录方便查看文件，但容易出现 UID/GID 权限问题。这里用命名卷。&lt;/p&gt;
&lt;p&gt;创建后点开详情，挂载点是 &lt;code&gt;/var/lib/docker/volumes/astrbot-data/_data&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/1panel/1panel-volume-create.png&quot; alt=&quot;1Panel 创建 astrbot-data 存储卷 w-100%&quot; title=&quot;创建名为 astrbot-data 的存储卷，详情里可以看到 Docker 的挂载路径&quot; /&gt;&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;填写基本信息&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;回到「容器」页面，点击「创建」。&lt;/p&gt;
&lt;p&gt;名称填 &lt;code&gt;astrbot&lt;/code&gt;，镜像勾选「手动输入」，填上面选中的地址。&lt;/p&gt;
&lt;p&gt;端口选「暴露端口」，添加 &lt;code&gt;6185:6185/tcp&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;「强制拉取镜像」首次安装可以不勾，更新镜像时勾上；「容器退出后自动删除容器」==不要勾选=={.error}。&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/1panel/1panel-container-create.png&quot; alt=&quot;1Panel 创建 astrbot 容器的基本信息 w-100%&quot; title=&quot;名称 astrbot，镜像 soulter/astrbot:latest，暴露 6185 端口&quot; /&gt;&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;配置网络&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;选择 ==&lt;code&gt;astrbot-network&lt;/code&gt;=={.primary}；MAC 地址、IPv4、IPv6、主机名、Domain、DNS 都留空，让 Docker 自动分配。&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/1panel/1panel-container-network.png&quot; alt=&quot;1Panel 容器网络选择 astrbot-network w-100%&quot; title=&quot;在容器的网络标签中选择 astrbot-network&quot; /&gt;&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;配置挂载&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;添加三条挂载：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;类型&lt;/th&gt;
&lt;th&gt;服务器&lt;/th&gt;
&lt;th&gt;容器目录&lt;/th&gt;
&lt;th&gt;权限&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;挂载卷&lt;/td&gt;
&lt;td&gt;&lt;code&gt;astrbot-data&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/AstrBot/data&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;读写&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;本机目录&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/etc/localtime&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/etc/localtime&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;只读&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;本机目录&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/etc/timezone&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/etc/timezone&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;只读&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;第一条把命名卷挂到数据目录；后两条同步宿主机时区。==&lt;code&gt;/etc/localtime&lt;/code&gt; 和 &lt;code&gt;/etc/timezone&lt;/code&gt; 都选只读=={.tip}。&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/1panel/1panel-container-mount.png&quot; alt=&quot;1Panel 容器挂载数据卷和时区文件 w-100%&quot; title=&quot;astrbot-data 挂载到 /AstrBot/data，localtime 和 timezone 以本机目录方式挂载，权限都选只读&quot; /&gt;&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;设置环境变量&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;添加环境变量 ==&lt;code&gt;TZ=Asia/Shanghai&lt;/code&gt;=={.primary}。&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/1panel/1panel-container-env.png&quot; alt=&quot;1Panel 容器环境变量设置时区 w-100%&quot; title=&quot;添加环境变量 TZ=Asia/Shanghai&quot; /&gt;&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;重启规则&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;这里对重启规则没有要求，随便选都可以。
:::&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;h2&gt;使用 compose 单独安装 Astrbot&lt;/h2&gt;
&lt;p&gt;:::tip[想使用 compose 安装 Astrbot?]
Compose的优势就是可以多个容器一起部署而且不需要上面的各种设置,一键启动即可.见 &lt;a href=&quot;/posts/deploy/astrbot-adapter-napcat/#%E6%96%B9%E5%BC%8F%E4%B8%89astrbot--napcat-%E4%B8%80%E8%B5%B7%E9%83%A8%E7%BD%B2&quot;&gt;NapCat 一起部署&lt;/a&gt; 和 &lt;a href=&quot;/posts/deploy/astrbot-adapter-snowluma/#22-astrbot--snowluma-%E4%B8%80%E8%B5%B7%E9%83%A8%E7%BD%B2&quot;&gt;SnowLuma 一起部署&lt;/a&gt;。&lt;/p&gt;
&lt;p&gt;问题是: 不同容器出现问题时, compose需要同时重启, 这个比较麻烦, 所以更推荐容器安装, 然后手动调整
:::&lt;/p&gt;
&lt;p&gt;:::steps[在 1Panel 中创建编排]&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;打开编排创建页&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;在 1Panel 中进入「编排 → 创建」，来源选「编辑」，名称填 &lt;code&gt;astrbot&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/1panel/1panel-compose-create.png&quot; alt=&quot;1Panel 编排创建页：来源选编辑，名称填 astrbot，粘贴 YAML 后保存 w-100%&quot; title=&quot;1Panel 编排创建页&quot; /&gt;&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;粘贴 YAML&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;YAML 中使用了 &lt;code&gt;astrbot-network&lt;/code&gt;，请先确认这个网络是否存在：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;不存在：保留 &lt;code&gt;driver: bridge&lt;/code&gt;，Compose 会创建网络（实际名称可能带项目前缀）。&lt;/li&gt;
&lt;li&gt;已存在：注释 &lt;code&gt;driver: bridge&lt;/code&gt;，取消 &lt;code&gt;external: true&lt;/code&gt; 的注释，复用已有网络。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;上面的截图仅展示 1Panel 编排创建页的填写方式，截图里的 YAML ==没有=={.primary} 包含这段 &lt;code&gt;networks&lt;/code&gt; 配置。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;services:
  astrbot:
    image: soulter/astrbot:latest
    container_name: astrbot
    restart: always
    security_opt:
      - no-new-privileges:true
    ports:
      - &quot;6185:6185&quot; # AstrBot WebUI
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - astrbot-data:/AstrBot/data
      # - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    networks:
      - astrbot-network

networks:
  astrbot-network:
    # 二选一：没有提前创建网络时用 driver；已创建时注释 driver，改用 external
    driver: bridge
    # external: true

volumes:
  astrbot-data:
    name: astrbot-data
&lt;/code&gt;&lt;/pre&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;保存并启动&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;点击「保存」，1Panel 会按这份编排创建容器。
:::&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;h1&gt;完成界面&lt;/h1&gt;
&lt;p&gt;部署完成后，浏览器打开 &lt;code&gt;http://&amp;lt;服务器IP&amp;gt;:6185&lt;/code&gt;，用日志里的初始密码登录。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;界面&lt;/th&gt;
&lt;th&gt;默认地址&lt;/th&gt;
&lt;th&gt;凭证&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;AstrBot WebUI&lt;/td&gt;
&lt;td&gt;&lt;code&gt;http://&amp;lt;服务器IP&amp;gt;:6185&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;日志中的 &lt;code&gt;Initial Password&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;:::steps[第一次登录]&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;获取初始密码&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;1Panel 里进入「容器」→ &lt;code&gt;astrbot&lt;/code&gt; → 「日志」；或者命令行执行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;docker logs astrbot 2&amp;gt;&amp;amp;1 | grep -i &quot;password&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;首次启动的日志里会出现 &lt;code&gt;Initial Password: xxxxxxxx&lt;/code&gt;，用户名通常是 &lt;code&gt;astrbot&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/verify/astrbot-initial-password.png&quot; alt=&quot;1Panel 中 AstrBot 启动日志里的初始用户名和密码 w-100%&quot; title=&quot;AstrBot v4.29.4 WebUI is ready，下面会打印 Initial username 和 Initial password&quot; /&gt;&lt;/p&gt;
&lt;p&gt;截图中的密码仅作示例，请以自己日志里的值为准。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;登录 WebUI&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;浏览器打开 &lt;code&gt;http://&amp;lt;服务器IP&amp;gt;:6185&lt;/code&gt;，用 &lt;code&gt;astrbot&lt;/code&gt; 和初始密码登录。打不开时先回看「查看端口」，确认 1Panel 防火墙和云厂商安全组都已放行 6185。&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/verify/astrbot-login.png&quot; alt=&quot;AstrBot WebUI 登录页 w-100%&quot; title=&quot;用户名 astrbot，密码填日志里的 Initial password&quot; /&gt;&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;修改密码并进入首页&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;登录后第一件事是改密码。6185 暴露在公网时，面板可以配置模型密钥、消息平台和插件，尽量不要把它开放给所有人。&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/Astrbot/verify/astrbot-dashboard.png&quot; alt=&quot;AstrBot WebUI 首页 w-100%&quot; title=&quot;在快速引导里继续配置模型和消息平台&quot; /&gt;
:::&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;h1&gt;常见问题&lt;/h1&gt;
&lt;p&gt;::: collapse&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;部署完成后为什么无法访问 6185 端口&lt;/p&gt;
&lt;p&gt;大概率是因为你没有在服务器厂商那里把==防火墙=={.primary}端口打开&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;想和 NapCat/SnowLuma 一起部署？&lt;/p&gt;
&lt;p&gt;见 &lt;a href=&quot;/posts/deploy/astrbot-adapter-napcat/#%E6%96%B9%E5%BC%8F%E4%B8%89astrbot--napcat-%E4%B8%80%E8%B5%B7%E9%83%A8%E7%BD%B2&quot;&gt;NapCat 一起部署&lt;/a&gt; 和 &lt;a href=&quot;/posts/deploy/astrbot-adapter-snowluma/#22-astrbot--snowluma-%E4%B8%80%E8%B5%B7%E9%83%A8%E7%BD%B2&quot;&gt;SnowLuma 一起部署&lt;/a&gt;。&lt;/p&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;:::&lt;/p&gt;
&lt;h1&gt;参考资料&lt;/h1&gt;
&lt;ul&gt;
&lt;li&gt;AstrBot Docker 部署：https://docs.astrbot.app/deploy/astrbot/docker.html&lt;/li&gt;
&lt;/ul&gt;
</content:encoded></item><item><title>1Panel 安装与初始化</title><link>https://blog.0v0.uno/posts/deploy/1panel/</link><guid isPermaLink="true">https://blog.0v0.uno/posts/deploy/1panel/</guid><description>在 Linux 服务器上安装 1Panel，完成初始化、安全设置和 Docker 环境准备。</description><pubDate>Thu, 12 Nov 2026 03:25:08 GMT</pubDate><content:encoded>&lt;p&gt;1Panel 是飞致云开源的 Linux 运维面板，官方网站为 &lt;a href=&quot;https://1panel.cn/&quot;&gt;1panel.cn&lt;/a&gt;，官方文档位于 &lt;a href=&quot;https://1panel.cn/docs/&quot;&gt;1panel.cn/docs&lt;/a&gt;。它把 Docker、应用商店、网站、防火墙、文件管理和计划任务集中到一个 Web 界面。&lt;/p&gt;
&lt;p&gt;这篇从一台刚买到的 Linux 服务器开始，装好 1Panel 并完成必要的安全设置。&lt;/p&gt;
&lt;h2&gt;1. 安装前准备&lt;/h2&gt;
&lt;h3&gt;1.1 系统要求&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;系统&lt;/strong&gt;：主流 Debian/RedHat 系 Linux，包括 Ubuntu、Debian、CentOS、Rocky Linux、AlmaLinux、openEuler 等。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;架构&lt;/strong&gt;：x86_64、aarch64、armv7l 等。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;内存&lt;/strong&gt;：建议可用内存 2 GB 以上&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;权限&lt;/strong&gt;：root 或具有 sudo 权限的用户。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;网络&lt;/strong&gt;：能访问外网；内网环境需要使用离线安装包。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;先更新系统，Ubuntu/Debian 使用：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;apt update &amp;amp;&amp;amp; apt upgrade -y
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;CentOS 7 使用：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;yum update -y
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;CentOS Stream 8/9、Rocky Linux、AlmaLinux 使用：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;dnf update -y
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;1.2 安装前放行面板端口&lt;/h3&gt;
&lt;p&gt;先确定 1Panel 面板端口为 &lt;code&gt;12345&lt;/code&gt;，并在安装前放行。端口统一在服务器厂商控制台的安全组或防火墙页面中设置：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;用途&lt;/th&gt;
&lt;th&gt;端口&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;SSH&lt;/td&gt;
&lt;td&gt;&lt;code&gt;22&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;1Panel 面板&lt;/td&gt;
&lt;td&gt;&lt;code&gt;12345&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;找到实例对应的安全组或防火墙，新增一条入站规则：协议选择 &lt;code&gt;TCP&lt;/code&gt;，端口填写 &lt;code&gt;12345&lt;/code&gt;。如果知道访问面板的公网 IP，来源地址应只允许该 IP；不要把面板端口无条件开放给整个互联网。&lt;/p&gt;
&lt;p&gt;以京东云为例，进入轻量应用服务器的设置界面，在“防火墙”页面点击“添加规则”，协议选择 &lt;code&gt;TCP&lt;/code&gt;，目标端口填写 &lt;code&gt;12345&lt;/code&gt;，保存后即可放行面板端口。&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;/images/posts/deploy/1panel/jd-cloud-firewall.png&quot; alt=&quot;京东云轻量应用服务器防火墙中添加 TCP 12345 规则 w-100%&quot; title=&quot;在京东云防火墙中放行 1Panel 面板端口&quot; /&gt;&lt;/p&gt;
&lt;h2&gt;2. 在线安装&lt;/h2&gt;
&lt;p&gt;1Panel v2 提供一键安装脚本，它会自动检测服务器的架构，然后下载对应的版本。使用 root 或 sudo 执行：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;bash -c &quot;$(curl -sSL https://resource.fit2cloud.com/1panel/package/v2/quick_start.sh)&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;脚本会依次询问：&lt;/p&gt;
&lt;p&gt;:::steps[交互式安装流程]&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;安装目录&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;默认 &lt;code&gt;/opt&lt;/code&gt;，没有特殊需求直接回车。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;[1Panel 2026-11-12 10:48:26 install Log]: ==== 开始安装 ====
设置 1Panel 安装目录（默认：/opt）：
[1Panel 2026-11-12 10:48:31 install Log]: 已选择安装路径： /opt
&lt;/code&gt;&lt;/pre&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;安装 Docker&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;安装 1Panel 的过程中会检测是否安装 Docker。没有安装 Docker 时会询问是否需要安装，一般选择 &lt;code&gt;y&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;安装脚本会自动安装 Docker。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;检测到未安装 Docker，是否安装 [y/n]（默认：y）：y
   [1Panel 2026-11-12 10:48:33 install Log]: ... 在线安装 Docker
   [1Panel 2026-11-12 10:48:39 install Log]: 请选择延迟最低的软件源 https://mirrors.aliyun.com/docker-ce，延迟（秒） 0.0504415
   [1Panel 2026-11-12 10:48:39 install Log]: 正在尝试下一个备用链接 https://get.docker.com 正在下载 Docker 安装脚本
   [1Panel 2026-11-12 10:48:41 install Log]: 已从以下地址下载 Docker 安装脚本： https://get.docker.com 成功
   # Executing docker install script, commit: 8ad27bd3ac871feabe62f1d926c4067800c1732f
   + sh -c apt-get -qq update &amp;gt;/dev/null
   + sh -c DEBIAN_FRONTEND=noninteractive apt-get -y -qq install ca-certificates curl &amp;gt;/dev/null
   + sh -c install -m 0755 -d /etc/apt/keyrings
   + sh -c curl -fsSL &quot;https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg&quot; -o /etc/apt/keyrings/docker.asc
   + sh -c chmod a+r /etc/apt/keyrings/docker.asc
   + sh -c echo &quot;deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.asc] https://mirrors.aliyun.com/docker-ce/linux/ubuntu noble stable&quot; &amp;gt; /etc/apt/sources.list.d/docker.list
   + sh -c apt-get -qq update &amp;gt;/dev/null
   + apt_flags=-y -qq
   + [ -n  ]
   + sh -c DEBIAN_FRONTEND=noninteractive apt-get -y -qq install docker-ce docker-ce-cli containerd.io docker-compose-plugin docker-ce-rootless-extras docker-buildx-plugin docker-model-plugin &amp;gt;/dev/null
   Using systemd to manage Docker service
   + sh -c systemctl enable --now docker.service 2&amp;gt;/dev/null
   INFO: Docker daemon enabled and started

   + sh -c docker version
   Client: Docker Engine - Community
   Version:           29.9.3
   API version:       1.56
   Go version:        go1.26.10
   Git commit:        5457199
   Built:             Tue Nov  3 21:41:31 2026
   OS/Arch:           linux/amd64
   Context:           default

   Server: Docker Engine - Community
   Engine:
   Version:          29.9.3
   API version:      1.56 (minimum version 1.40)
   Go version:       go1.26.10
   Git commit:       70efc0e
   Built:            Tue Nov  3 21:41:31 2026
   OS/Arch:          linux/amd64
   Experimental:     false
   containerd:
   Version:          v2.4.2
   GitCommit:        b7a25261e029d68978bbf290df0a62fc819b3c51
   runc:
   Version:          1.5.2
   GitCommit:        v1.5.2-0-g29dd3dc2
   docker-init:
   Version:          0.19.0
   GitCommit:        de40ad0

   ================================================================================

   To run Docker as a non-privileged user, consider setting up the
   Docker daemon in rootless mode for your user:

      dockerd-rootless-setuptool.sh install

   Visit https://docs.docker.com/go/rootless/ to learn about rootless mode.


   To run the Docker daemon as a fully privileged service, but granting non-root
   users access, refer to https://docs.docker.com/go/daemon-access/

   WARNING: Access to the remote API on a privileged Docker daemon is equivalent
            to root access on the host. Refer to the &apos;Docker daemon attack surface&apos;
            documentation for details: https://docs.docker.com/go/attack-surface/

   ================================================================================

   [1Panel 2026-11-12 10:54:14 install Log]: Docker 安装成功
   Synchronizing state of docker.service with SysV service script with /usr/lib/systemd/systemd-sysv-install.
   Executing: /usr/lib/systemd/systemd-sysv-install enable docker
   是否要配置镜像加速 [y/n]（默认：y）：y
   [1Panel 2026-11-12 10:54:18 install Log]: 创建新配置文件 /etc/docker/daemon.json...
   [1Panel 2026-11-12 10:54:18 install Log]: 已添加镜像加速配置。
   [1Panel 2026-11-12 10:54:18 install Log]: 正在重启 Docker 服务...
   [1Panel 2026-11-12 10:54:19 install Log]: Docker 服务已成功重启。
&lt;/code&gt;&lt;/pre&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;面板端口&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;输入已经放行的 &lt;code&gt;12345&lt;/code&gt;。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;   设置 1Panel 端口（默认： &amp;lt;随机端口&amp;gt;): 12345
   [1Panel 2026-11-12 10:54:23 install Log]: 已设置端口： 12345
   [1Panel 2026-11-12 10:54:23 install Log]: 正在打开防火墙端口 12345
   Rules updated
   Rules updated (v6)
   Firewall not enabled (skipping reload)
&lt;/code&gt;&lt;/pre&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;安全入口&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;相当于面板 URL 的隐藏路径，例如 &lt;code&gt;panel-a1b2c3&lt;/code&gt;。不要用 &lt;code&gt;admin&lt;/code&gt;、&lt;code&gt;login&lt;/code&gt; 这类容易猜到的值。&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;[!TIP]
建议安全入口跟后续设置的用户名保持一致，方便记忆。例如安全入口设为 &lt;code&gt;panel-a1b2c3&lt;/code&gt;，最终访问地址就是 &lt;code&gt;http://&amp;lt;服务器IP&amp;gt;:&amp;lt;端口&amp;gt;/panel-a1b2c3&lt;/code&gt;。&lt;/p&gt;
&lt;/blockquote&gt;
&lt;pre&gt;&lt;code&gt;   设置 1Panel 安全入口（默认： &amp;lt;随机安全入口&amp;gt;): &amp;lt;自定义安全入口&amp;gt;
   [1Panel 2026-11-12 10:54:34 install Log]: 已设置面板安全入口： &amp;lt;已隐藏&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;用户名和密码&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;用户名 3–30 位字母、数字或下划线；密码 8–30 位，支持字母、数字和 &lt;code&gt;_!@#$%*,.?&lt;/code&gt;。建议用密码管理器生成。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;是否配置镜像加速&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;国内服务器建议选 &lt;code&gt;y&lt;/code&gt;；如果已经有可用的加速配置，选 &lt;code&gt;n&lt;/code&gt; 以免覆盖。
:::&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;安装完成后，终端会打印访问地址，格式为：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;   [1Panel 2026-11-12 10:54:48 install Log]: 1Panel 服务已成功启动，正在继续执行后续配置，请稍候...
   [1Panel 2026-11-12 10:54:48 install Log]:
   [1Panel 2026-11-12 10:54:48 install Log]: =================感谢您的耐心等待，安装已完成==================
   [1Panel 2026-11-12 10:54:48 install Log]:
   [1Panel 2026-11-12 10:54:48 install Log]: 请使用您的浏览器访问面板：
   [1Panel 2026-11-12 10:54:48 install Log]: 外部地址： http://&amp;lt;服务器公网IP&amp;gt;:12345/&amp;lt;安全入口&amp;gt;
   [1Panel 2026-11-12 10:54:48 install Log]: 内部地址： http://&amp;lt;服务器内网IP&amp;gt;:12345/&amp;lt;安全入口&amp;gt;
   [1Panel 2026-11-12 10:54:48 install Log]: 面板用户： &amp;lt;已隐藏&amp;gt;
   [1Panel 2026-11-12 10:54:48 install Log]: 面板密码： &amp;lt;已隐藏&amp;gt;
   [1Panel 2026-11-12 10:54:48 install Log]:
   [1Panel 2026-11-12 10:54:48 install Log]: 官方网站：https://1panel.cn
   [1Panel 2026-11-12 10:54:48 install Log]: 项目文档：https://1panel.cn/docs
   [1Panel 2026-11-12 10:54:48 install Log]: 代码仓库：https://github.com/1Panel-dev/1Panel
   [1Panel 2026-11-12 10:54:48 install Log]: 前往 1Panel 官方论坛获取帮助：https://bbs.fit2cloud.com/c/1p/7
   [1Panel 2026-11-12 10:54:48 install Log]:
   [1Panel 2026-11-12 10:54:48 install Log]: 如果您使用的是云服务器，请在安全组中打开端口 12345
   [1Panel 2026-11-12 10:54:48 install Log]:
   [1Panel 2026-11-12 10:54:48 install Log]: 为了您的服务器安全，离开此屏幕后您将无法再次看到您的密码，请记住您的密码。
   [1Panel 2026-11-12 10:54:48 install Log]:
   [1Panel 2026-11-12 10:54:48 install Log]: ================================================================
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;3. 内网离线安装&lt;/h2&gt;
&lt;p&gt;服务器不能访问公网时，可以使用 1Panel V2 离线包。离线包已预置 Docker 和常用应用镜像，不需要在安装过程中下载依赖。&lt;/p&gt;
&lt;p&gt;:::important[离线安装的是企业试用版]
1Panel 离线安装包已集成企业版核心功能。安装完成后会进入 7 天企业版全功能试用期，并不会直接安装为社区版。试用结束后，登录页会要求导入许可证，需要手动恢复社区版。
:::&lt;/p&gt;
&lt;h3&gt;3.1 获取官方离线包&lt;/h3&gt;
&lt;p&gt;前往 &lt;a href=&quot;https://community.fit2cloud.com/#/products/1panel/downloads&quot;&gt;FIT2CLOUD 开源社区下载页面&lt;/a&gt; 下载 1Panel 企业版离线安装包。官方文档目前提供 x86_64（amd64）架构的离线包，用于首次安装和后续升级。&lt;/p&gt;
&lt;p&gt;:::warning[升级和恢复使用不同安装包]
企业版离线包可以用于安装和升级。试用到期后恢复社区版时，不能继续使用这个离线包，需要在登录页点击“复制下载链接”，重新下载版本不低于当前企业版的社区版安装包。
:::&lt;/p&gt;
&lt;p&gt;具体内容以 &lt;a href=&quot;https://docs.fit2cloud.com/1panel/installation/enterprise-installation&quot;&gt;1Panel 官方离线安装文档&lt;/a&gt; 为准。&lt;/p&gt;
&lt;h3&gt;3.2 上传并安装&lt;/h3&gt;
&lt;p&gt;先在内网可访问的跳板机或管理机上准备离线包，然后上传到目标服务器。以下载到当前目录的 &lt;code&gt;1panel-v2.x.x-offline-linux-amd64.tar.gz&lt;/code&gt; 为例：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;scp 1panel-v2.x.x-offline-linux-amd64.tar.gz root@&amp;lt;服务器IP&amp;gt;:/tmp/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;SSH 登录内网服务器，以 root 用户解压并运行安装脚本：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;cd /tmp
tar -zxvf 1panel-v2.x.x-offline-linux-amd64.tar.gz
cd 1panel-v2.x.x-offline-linux-amd64
bash install.sh
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;安装脚本提示设置面板端口时输入 &lt;code&gt;12345&lt;/code&gt;。安装目录、安全入口、用户名、密码和 Docker 选项与在线安装一致。安装完成后，在浏览器访问：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;http://&amp;lt;服务器IP&amp;gt;:12345/&amp;lt;安全入口&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;3.3 试用到期后恢复社区版&lt;/h3&gt;
&lt;p&gt;7 天企业版试用结束后，1Panel 不会自动切回社区版。面板仍会要求导入许可证，需要按以下步骤手动恢复：&lt;/p&gt;
&lt;p&gt;:::steps[恢复社区版]&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;打开登录页&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;浏览器访问 1Panel 登录页面。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;选择恢复社区版&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;单击登录页右上角的 &lt;strong&gt;恢复社区版&lt;/strong&gt;。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;选择恢复方式&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;在弹窗中选择恢复方式：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;服务器可以访问互联网时，选择 &lt;strong&gt;在线恢复&lt;/strong&gt;。&lt;/li&gt;
&lt;li&gt;内网或服务器无法访问外网时，选择 &lt;strong&gt;离线恢复&lt;/strong&gt;。&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;复制社区版下载链接&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;选择 &lt;strong&gt;离线恢复&lt;/strong&gt; 后，在弹窗中单击 &lt;strong&gt;复制下载链接&lt;/strong&gt;。社区版安装包会使用这个链接下载，版本不能低于当前企业版。&lt;/p&gt;
&lt;p&gt;这一步需要在能访问互联网的设备上完成，因为内网服务器无法直接下载。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;上传社区版安装包&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;将下载得到的社区版安装包上传到服务器的恢复目录。目录不存在时先创建：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;mkdir -p /opt/1panel/tmp/community-restore
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;从其他设备上传安装包：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;scp &amp;lt;社区版安装包&amp;gt; root@&amp;lt;服务器IP&amp;gt;:/opt/1panel/tmp/community-restore/
&lt;/code&gt;&lt;/pre&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;确认恢复&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;确认社区版安装包已经放入 &lt;code&gt;/opt/1panel/tmp/community-restore&lt;/code&gt;，然后回到恢复弹窗单击 &lt;strong&gt;确认&lt;/strong&gt;。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;重新登录&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;切换完成后，使用恢复前的企业版超级管理员账号和密码登录。
:::&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;:::warning[不要放入企业版离线包]
恢复社区版时，不能把第 3.1 节下载的企业版离线包放入 &lt;code&gt;/opt/1panel/tmp/community-restore&lt;/code&gt;。放错文件后切换过程仍可能执行完成，但面板依然是企业版，再次登录仍会回到许可证页面，账号和密码也可能被重置为 &lt;code&gt;username&lt;/code&gt; 和 &lt;code&gt;password&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;如果账号已经被重置，可以在服务器上重新设置：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;1pctl update username
1pctl update password
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::&lt;/p&gt;
&lt;p&gt;:::note[版本切换后的数据]
恢复社区版会清除企业版专属数据，基础功能可以继续使用。切换完成后，使用恢复前的企业版超级管理员账号登录社区版。
:::&lt;/p&gt;
&lt;h2&gt;4. 常用命令&lt;/h2&gt;
&lt;pre&gt;&lt;code&gt;1pctl user-info
1pctl status
1pctl restart
&lt;/code&gt;&lt;/pre&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;1pctl user-info&lt;/code&gt;：查看面板地址、安全入口和用户名。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;1pctl status&lt;/code&gt;：查看 1Panel 服务状态。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;1pctl restart&lt;/code&gt;：重启面板服务。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;升级面板在 Web 界面右下角检查更新，或按官方文档执行升级命令。升级前先做快照。&lt;/p&gt;
&lt;h2&gt;5. 常见问题&lt;/h2&gt;
&lt;p&gt;::: collapse&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;面板打不开&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;按顺序检查：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;服务器厂商的安全组或防火墙是否放行 &lt;code&gt;TCP 12345&lt;/code&gt;；&lt;/li&gt;
&lt;li&gt;安装时是否将面板端口设置为 &lt;code&gt;12345&lt;/code&gt;；&lt;/li&gt;
&lt;li&gt;&lt;code&gt;1pctl status&lt;/code&gt; 是否显示服务正常；&lt;/li&gt;
&lt;li&gt;访问地址是否包含安全入口；&lt;/li&gt;
&lt;li&gt;本机能否访问：&lt;code&gt;curl -I http://127.0.0.1:12345&lt;/code&gt;。&lt;/li&gt;
&lt;/ol&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Docker 安装失败&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;可以尝试使用镜像站脚本单独安装 Docker：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;bash &amp;lt;(curl -sSL https://linuxmirrors.cn/docker.sh)
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;安装完成后回到 1Panel 容器页面确认状态。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;忘记安全入口&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;1pctl user-info
&lt;/code&gt;&lt;/pre&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;拉取镜像很慢&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;优先配置镜像加速；其次在 Compose 文件中把镜像地址替换为带加速前缀的地址。不要同时配置多个互相冲突的加速源。
:::&lt;/p&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;6. 参考资料&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;1Panel 在线安装：https://1panel.cn/docs/v2/installation/online_installation/&lt;/li&gt;
&lt;li&gt;1Panel 离线安装：https://docs.fit2cloud.com/1panel/installation/enterprise-installation&lt;/li&gt;
&lt;li&gt;1Panel 命令行工具：https://1panel.cn/docs/v2/installation/cli/&lt;/li&gt;
&lt;/ul&gt;
</content:encoded></item><item><title>服务器选购(海外)</title><link>https://blog.0v0.uno/posts/deploy/server/</link><guid isPermaLink="true">https://blog.0v0.uno/posts/deploy/server/</guid><description>腾讯云的新加坡与美国轻量服务器：30M 起步，直连海外 API，适合长期在线的业务。</description><pubDate>Wed, 11 Nov 2026 13:20:00 GMT</pubDate><content:encoded>&lt;p&gt;选海外服务器时，国内机器不是不能跑，而是不划算：带宽通常只有 1–5 Mbps，访问 OpenAI、Gemini、Claude 等海外服务往往得再维护一层代理。&lt;/p&gt;
&lt;p&gt;把机器放到==新加坡或美国=={.primary}，带宽直接上到 30 Mbps 起步，海外 API 直连，省掉代理的麻烦。这篇只讲腾讯云的新加坡和美国节点，以及不同用途该怎么选配置。&lt;/p&gt;
&lt;h2&gt;1. 为什么是新加坡和美国&lt;/h2&gt;
&lt;h3&gt;1.1 新加坡&lt;/h3&gt;
&lt;p&gt;新加坡是==亚太的网络枢纽=={.primary}，海底光缆密集，到世界各地都有直连线路：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;到中国大陆约 60–90 ms，到东南亚约 20–50 ms，到美西约 150–200 ms。&lt;/li&gt;
&lt;li&gt;对 OpenAI、Gemini、Claude 等海外 API 通常可以直连，不需要在服务器上再跑代理。&lt;/li&gt;
&lt;li&gt;适合挂 QQ、Telegram、Discord 机器人，也适合面向亚太用户的网站。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;缺点是晚高峰到中国大陆的线路可能拥堵，热门套餐也==经常缺货=={.error}。腾讯云新加坡轻量就属于经常抢不到的地域。&lt;/p&gt;
&lt;h3&gt;1.2 美国&lt;/h3&gt;
&lt;p&gt;美国节点主要有==硅谷和弗吉尼亚=={.primary}两个方向：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;到中国大陆约 150–220 ms，延迟比新加坡高，但==带宽充足、价格低、库存稳定=={.tip}。&lt;/li&gt;
&lt;li&gt;访问美国本土 API 的延迟最低，适合 OpenAI、Anthropic 以及各种美国服务。&lt;/li&gt;
&lt;li&gt;适合对延迟不敏感、但流量较大的场景：机器人、下载、镜像、备份。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;国内用户打开美国机器的 Web 面板会明显变慢，但大多数后台任务和 API 调用对这点延迟不敏感，实际使用没有太大区别。&lt;/p&gt;
&lt;h3&gt;1.3 其他地区&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;地区&lt;/th&gt;
&lt;th&gt;特点&lt;/th&gt;
&lt;th&gt;结论&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;新加坡&lt;/td&gt;
&lt;td&gt;亚太枢纽，国内延迟低，国际线路好&lt;/td&gt;
&lt;td&gt;==首选=={.primary}&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;美国硅谷&lt;/td&gt;
&lt;td&gt;带宽大、库存稳、美国 API 延迟低&lt;/td&gt;
&lt;td&gt;==首选=={.primary}&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;中国香港&lt;/td&gt;
&lt;td&gt;国内延迟最低，但带宽贵、国际出口一般&lt;/td&gt;
&lt;td&gt;==预算充足再考虑=={.secondary}&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;日本、韩国&lt;/td&gt;
&lt;td&gt;延迟低，但大厂套餐少、线路稳定性一般&lt;/td&gt;
&lt;td&gt;==不作为首选=={.tertiary}&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;欧洲&lt;/td&gt;
&lt;td&gt;到国内延迟高，适合欧洲用户&lt;/td&gt;
&lt;td&gt;按用户分布选择&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;对大多数在线服务来说，==100–200 ms 的延迟完全可用=={.tip}。真正影响体验的是带宽和流量，所以优先选 30 Mbps 以上的套餐，而不是纠结那几十毫秒。&lt;/p&gt;
&lt;h2&gt;2. 大厂套餐怎么选&lt;/h2&gt;
&lt;p&gt;海外服务器目前只推荐==腾讯云=={.primary}。它的国际线路、库存和售后比较稳定，价格也透明；其它厂商要么活动少，要么热门地域经常缺货。&lt;/p&gt;
&lt;h3&gt;2.1 腾讯云轻量应用服务器&lt;/h3&gt;
&lt;p&gt;腾讯云的海外轻量（&lt;a href=&quot;https://cloud.tencent.com/product/lighthouse&quot;&gt;Lighthouse&lt;/a&gt;）==活动最频繁=={.primary}，新加坡和硅谷同价。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;项目&lt;/th&gt;
&lt;th&gt;参考配置&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;CPU / 内存&lt;/td&gt;
&lt;td&gt;2 核 2 GB（入门），2 核 4 GB（推荐）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;带宽&lt;/td&gt;
&lt;td&gt;30 Mbps 峰值&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;系统盘&lt;/td&gt;
&lt;td&gt;50–60 GB SSD&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;月流量&lt;/td&gt;
&lt;td&gt;1–1.5 TB&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;地域&lt;/td&gt;
&lt;td&gt;新加坡、美国硅谷、东京、首尔、法兰克福等&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;价格分两种渠道：&lt;/p&gt;
&lt;p&gt;:::tabs&lt;/p&gt;
&lt;p&gt;@tab 中国站&lt;/p&gt;
&lt;p&gt;海外地域活动价常见 &lt;code&gt;99 元/年&lt;/code&gt;（2C2G/30M/1TB）和 &lt;code&gt;199 元/年&lt;/code&gt;（2C4G/30M/1.5TB），支持支付宝，需要实名。购买和续费尽量走&lt;a href=&quot;https://cloud.tencent.com/act?Is=sdk-topnav&quot;&gt;腾讯云活动页&lt;/a&gt;，活动页通常提供一次“==同价续费=={.tip}”；==不要直接按日常价续费=={.error}，控制台直接续费是原价，差价很大。&lt;/p&gt;
&lt;p&gt;@tab 国际站&lt;/p&gt;
&lt;p&gt;2C2G/30M/1TB 约 &lt;code&gt;$4.9–5.2/月&lt;/code&gt;，活动款曾出现 &lt;code&gt;$10.08/年&lt;/code&gt;（2C2G/20M/512GB）。国际站用美元结算，支持信用卡。&lt;/p&gt;
&lt;p&gt;:::&lt;/p&gt;
&lt;p&gt;中国站的 &lt;code&gt;199 元/年&lt;/code&gt;（2C4G/30M/1.5TB，硅谷）是==日常折扣价=={.secondary}，日常价 504 元/年；到了 1024 程序员节、双 11 这类节点，同档可低至 ==79 元/年=={.primary} 左右。不急用可以等活动，急用再按 199 元买。&lt;/p&gt;
&lt;p&gt;:::tip[按月购买]
不走活动直接月付时，镜像选 ==Ubuntu LTS=={.primary}（系统干净，后面装 1Panel 和 Docker 少踩坑），规格选入门型或锐驰型：入门型便宜、带宽低，锐驰型是 200M 峰值不限流量。==2C4G=={.primary}、带宽按需选择，月付控制在 ==60 元以内=={.tip} 就很划算。地域优先==新加坡二区=={.primary}，部分时段国内访问质量不错，但官方不承诺直连，晚高峰仍可能拥堵。
:::&lt;/p&gt;
&lt;p&gt;线路方面，新加坡和硅谷走中国电信 CN2、联通 AS4837、移动 CMI/CMNET。社区反馈硅谷晚高峰更稳，新加坡更容易拥堵；新加坡和东京经常缺货，硅谷库存相对充足。&lt;/p&gt;
&lt;h3&gt;2.2 套餐小结&lt;/h3&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;厂商&lt;/th&gt;
&lt;th&gt;产品&lt;/th&gt;
&lt;th&gt;入门配置&lt;/th&gt;
&lt;th&gt;带宽 / 流量&lt;/th&gt;
&lt;th&gt;参考价&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;腾讯云&lt;/td&gt;
&lt;td&gt;轻量 Lighthouse&lt;/td&gt;
&lt;td&gt;2C2G / 50G&lt;/td&gt;
&lt;td&gt;30M 峰值 / 1TB 月流量&lt;/td&gt;
&lt;td&gt;中国站 99 元/年起；国际站约 $5/月&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;:::tip[选购顺序]
先用地域筛掉不合适的节点，再用内存筛掉不够用的配置，最后比较中国站和国际站的价格。地域选错只能迁移，配置不够还可以升。
:::&lt;/p&gt;
&lt;h2&gt;3. 配置怎么选&lt;/h2&gt;
&lt;h3&gt;3.1 内存优先&lt;/h3&gt;
&lt;p&gt;这类在线服务通常不跑本地模型推理，真正吃资源的是系统、&lt;a href=&quot;/posts/deploy/1panel/&quot;&gt;1Panel&lt;/a&gt;、Docker 和常驻进程。内存按实际运行的容器数量估算：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;场景&lt;/th&gt;
&lt;th&gt;建议配置&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;单个轻量服务 + 1Panel&lt;/td&gt;
&lt;td&gt;2 核 2 GB&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;多个 Docker 容器、反向代理、数据库&lt;/td&gt;
&lt;td&gt;2 核 4 GB&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;多个业务实例、代码沙盒&lt;/td&gt;
&lt;td&gt;4 核 4 GB 以上&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;==不要买 1 核 1 GB=={.error}。系统、Docker 和面板会吃掉大半内存，更新镜像或同时跑两个容器时很容易 OOM。2 GB 内存建议再加 ==1–2 GB swap=={.tip} 兜底。&lt;/p&gt;
&lt;h3&gt;3.2 磁盘和带宽&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;系统盘 40 GB 起步&lt;/strong&gt;：Docker 镜像、日志、业务数据和备份都会持续增长，60 GB 更从容。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;带宽 30 Mbps 足够&lt;/strong&gt;：纯文本服务每月的流量通常只有几 GB，1 TB 的月流量包基本用不完；图片、文件下载和大流量业务才会明显消耗流量。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;流量超额&lt;/strong&gt;：腾讯云约 &lt;code&gt;$0.077–0.081/GB&lt;/code&gt;，注意套餐的流量包大小。&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;3.3 地域怎么选&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;主要面向国内用户：优先==新加坡=={.primary}，延迟比美国低。&lt;/li&gt;
&lt;li&gt;主要调用 OpenAI、Anthropic 等美国 API：==硅谷=={.primary}更合适，延迟最低。&lt;/li&gt;
&lt;li&gt;同时服务国内和海外用户：新加坡折中。&lt;/li&gt;
&lt;li&gt;只调用 DeepSeek、通义千问、Kimi 等国内 API，且用户都在国内：国内服务器延迟低，但带宽低，选购见&lt;a href=&quot;/posts/deploy/server-cn/&quot;&gt;国内轻量服务器优惠汇总&lt;/a&gt;。&lt;/li&gt;
&lt;li&gt;新加坡和美国通常在 OpenAI、Gemini、Anthropic 的支持地区列表内，购买前以官方列表为准。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;:::info[国内服务器与备案]
国内低价轻量服务器见&lt;a href=&quot;/posts/deploy/server-cn/&quot;&gt;国内轻量服务器优惠汇总&lt;/a&gt;；ICP 备案流程见&lt;a href=&quot;/posts/deploy/icp-filing/&quot;&gt;ICP 备案指南&lt;/a&gt;。这两篇是独立文章，不在本系列里。
:::&lt;/p&gt;
&lt;h2&gt;4. 总结&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;决策点&lt;/th&gt;
&lt;th&gt;建议&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;地域&lt;/td&gt;
&lt;td&gt;==首选新加坡=={.primary}；要稳定库存或美国 API 选硅谷&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;厂商&lt;/td&gt;
&lt;td&gt;腾讯云&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;配置&lt;/td&gt;
&lt;td&gt;2 核 2 GB 起步，2 核 4 GB 更稳&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;带宽&lt;/td&gt;
&lt;td&gt;30 Mbps 起步；要大带宽选锐驰型&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;流量&lt;/td&gt;
&lt;td&gt;1 TB/月足够，注意超额单价&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;系统盘&lt;/td&gt;
&lt;td&gt;40 GB 起步，60 GB 更从容&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;系统&lt;/td&gt;
&lt;td&gt;Ubuntu 22.04/24.04 LTS 或 Debian 12&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;续费&lt;/td&gt;
&lt;td&gt;优先走活动页同价续费，不按日常价续&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2&gt;5. 参考资料&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://cloud.tencent.com/product/lighthouse&quot;&gt;腾讯云轻量应用服务器&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://cloud.tencent.com/document/product/1207/44755&quot;&gt;腾讯云轻量实例套餐&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://cloud.tencent.com/document/product/1207/50103&quot;&gt;腾讯云轻量地域与网络连通性&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://www.tencentcloud.com/products/lighthouse&quot;&gt;腾讯云国际站 Lighthouse&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
</content:encoded></item><item><title>AstrBot 在 Windows 上部署</title><link>https://blog.0v0.uno/posts/deploy/astrbot-win/</link><guid isPermaLink="true">https://blog.0v0.uno/posts/deploy/astrbot-win/</guid><description>使用 AstrBot Desktop 或 Launcher 在 Windows 上部署.</description><pubDate>Wed, 11 Nov 2026 13:07:27 GMT</pubDate><content:encoded>&lt;h1&gt;使用Astrbot-Desktop部署(推荐)&lt;/h1&gt;
&lt;h2&gt;特点&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;AstrBot-desktop&lt;/strong&gt; 适合在本地电脑快速部署和使用 AstrBot, 支持 ==Windows=={.primary}、==macOS=={.secondary}、==Linux=={.secondary}&lt;/p&gt;
&lt;p&gt;但是在 MacOS 和 Linux 中, 个人更推荐使用==源代码部署=={.primary}或者 ==Docker 部署=={.primary}&lt;/p&gt;
&lt;h2&gt;下载并安装&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;打开 &lt;a href=&quot;https://github.com/AstrBotDevs/AstrBot-desktop&quot;&gt;AstrBot-desktop Releases&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;下载与你系统对应的安装包(如 .exe、.dmg、.rpm、.deb).&lt;/li&gt;
&lt;li&gt;安装完成后启动桌面客户端,按向导完成初始化.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2&gt;常见问题&lt;/h2&gt;
&lt;p&gt;::: collapse accordion&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;是否需要python等环境&lt;/p&gt;
&lt;p&gt;不需要, Desktop下载的安装包中会自带Python环境, 所有的内容都是已经打包好的&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;是否需要初始密码&lt;/p&gt;
&lt;p&gt;不需要, Desktop==初次启动时=={.primary}, 初始密码输入自动是跳过的&lt;/p&gt;
&lt;p&gt;如果是docker或者源代码部署, 在终端中可以查看到初始默认密码&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;    [00:27:40.590] [Core] [INFO] [dashboard.server:523]:
    ✨✨✨
    AstrBot v4.24.3 WebUI is ready

    ➜  Local: http://localhost:6185
    ➜  Initial username: astrbot
    ➜  Initial password: UiYVpZxnW8k22IWqf0ru5pOy
    ➜  Change it after logging in
    ✨✨✨
    Set dashboard.host in data/cmd_config.json to enable remote access.
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;如果出现了需要输入密码的情况, 请这样做:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;停止 &lt;code&gt;AstrBot&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;删除 &lt;code&gt;AstrBot&lt;/code&gt; 的 &lt;code&gt;data&lt;/code&gt; 目录下的 &lt;code&gt;dist&lt;/code&gt; 文件夹,即 &lt;code&gt;AstrBot/data/dist&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;重新启动 &lt;code&gt;AstrBot&lt;/code&gt;&lt;/li&gt;
&lt;/ol&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;通过 AstrBot 桌面客户端安装的 AstrBot,data 目录在哪？&lt;/p&gt;
&lt;p&gt;在家目录下的 &lt;code&gt;.astrbot&lt;/code&gt; 目录下.&lt;/p&gt;
&lt;p&gt;:::tabs&lt;/p&gt;
&lt;p&gt;@tab Windows&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;  C:\Users\你的用户名\.astrbot
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;@tab Linux&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;  /home/你的用户名/.astrbot
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;@tab MacOS&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;  /Users/你的用户名/.astrbot
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::&lt;/p&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;:::&lt;/p&gt;
&lt;h1&gt;使用Astrbot-Launcher部署(不推荐)&lt;/h1&gt;
&lt;h2&gt;特点&lt;/h2&gt;
&lt;p&gt;AstrBot 一键启动器支持 Windows、MacOS、Linux 等多端部署&lt;/p&gt;
&lt;h2&gt;安装选择&lt;/h2&gt;
&lt;p&gt;对于==操作系统=={.primary}, 有Windows, Linux, MacOS三种操作系统. 对于==CPU=={.primary}, 有x64, ARM64和其他种类&lt;/p&gt;
&lt;p&gt;一共有很多种组合, 请按照需求下载&lt;/p&gt;
&lt;p&gt;前往&lt;a href=&quot;https://github.com/AstrBotDevs/astrbot-launcher&quot;&gt;下载页面&lt;/a&gt;下载对应版本&lt;/p&gt;
&lt;p&gt;:::tabs&lt;/p&gt;
&lt;p&gt;@tab Windows&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Windows x64:下载 EXE 安装包 AstrBot.Launcher_{版本}_x64-setup.exe&lt;/li&gt;
&lt;li&gt;Windows ARM64:下载 EXE 安装包 AstrBot.Launcher_{版本}_arm64-setup.exe&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;@tab Linux&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Debian / Ubuntu(x64):下载 DEB 包 AstrBot.Launcher_{版本}_amd64.deb&lt;/li&gt;
&lt;li&gt;Fedora / openSUSE / RHEL / CentOS(x64):下载 RPM 包 AstrBot.Launcher-{版本}-1.x86_64.rpm&lt;/li&gt;
&lt;li&gt;其他 Linux 发行版(x64,通用):下载 AppImage AstrBot.Launcher_{版本}_amd64.AppImage&lt;/li&gt;
&lt;li&gt;Debian / Ubuntu(ARM64):下载 DEB 包 AstrBot.Launcher_{版本}_arm64.deb&lt;/li&gt;
&lt;li&gt;Fedora / openSUSE / RHEL / CentOS(ARM64):下载 RPM 包 AstrBot.Launcher-{版本}-1.aarch64.rpm&lt;/li&gt;
&lt;li&gt;其他 Linux 发行版(ARM64,通用):下载 AppImage AstrBot.Launcher_{版本}_aarch64.AppImage&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;@tab MacOS&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;macOS Intel (x64):下载 DMG 安装包 AstrBot.Launcher_{版本}_x64.dmg&lt;/li&gt;
&lt;li&gt;macOS Apple Silicon (ARM64):下载 DMG 安装包 AstrBot.Launcher_{版本}_aarch64.dmg&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;:::&lt;/p&gt;
</content:encoded></item><item><title>Markdown 缩略词</title><link>https://blog.0v0.uno/posts/markdown-guide/abbreviations/</link><guid isPermaLink="true">https://blog.0v0.uno/posts/markdown-guide/abbreviations/</guid><description>只定义一次常见缩写，让全称在正文里随时可查。</description><pubDate>Fri, 06 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;缩略词让技术写作保持紧凑，同时为需要的读者保留完整术语。定义过的术语会渲染为原生 &lt;code&gt;abbr&lt;/code&gt; 元素，悬浮时和辅助技术都能读到全称。&lt;/p&gt;
&lt;h2&gt;写法与效果&lt;/h2&gt;
&lt;p&gt;在文章任意位置（通常放文末）用 &lt;code&gt;*[术语]: 全称&lt;/code&gt; 定义，正文里出现的对应术语会自动获得悬浮释义。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;写法&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;*[SSR]: Server-Side Rendering
*[LCP]: Largest Contentful Paint
*[CLS]: Cumulative Layout Shift

SSR 优先的输出让初始文档在 JavaScript 运行前就可见。
衡量其阅读体验时，LCP 和 CLS 能反映首屏内容是否快速且稳定。
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;渲染效果&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;*[SSR]: Server-Side Rendering
*[LCP]: Largest Contentful Paint
*[CLS]: Cumulative Layout Shift&lt;/p&gt;
&lt;p&gt;SSR 优先的输出让初始文档在 JavaScript 运行前就可见。衡量其阅读体验时，LCP 和 CLS 能反映首屏内容是否快速且稳定。&lt;/p&gt;
&lt;h2&gt;不受影响的场景&lt;/h2&gt;
&lt;p&gt;缩写也可以出现在普通 Markdown 旁，比如 &lt;strong&gt;SSR&lt;/strong&gt; 加粗文本；但 &lt;code&gt;SSR&lt;/code&gt; 这样的字面行内代码和 &lt;a href=&quot;https://web.dev/articles/lcp&quot;&gt;LCP 文档&lt;/a&gt; 这样的链接保持原样，不会被转换。&lt;/p&gt;
&lt;h2&gt;写作边界&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;术语必须以字母或数字开头，可含字母、数字、句点、下划线、加号、连字符。&lt;/li&gt;
&lt;li&gt;定义行不会渲染为可见段落，只对当前文章生效。&lt;/li&gt;
&lt;li&gt;非法或重复的定义保留为普通 Markdown，不会静默替换别的术语。&lt;/li&gt;
&lt;/ul&gt;
</content:encoded></item><item><title>Markdown 提示容器（Admonitions）</title><link>https://blog.0v0.uno/posts/markdown-guide/admonitions/</link><guid isPermaLink="true">https://blog.0v0.uno/posts/markdown-guide/admonitions/</guid><description>用 Shirone 的 M3E Markdown 容器呈现备注、警告与可折叠的可选细节。</description><pubDate>Fri, 06 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;提示容器让补充信息在视觉上与正文区分开，同时不破坏阅读流。所有形式都在服务端渲染，共用同一套紧凑的 M3E 组件。&lt;/p&gt;
&lt;h2&gt;各类型写法与效果&lt;/h2&gt;
&lt;p&gt;支持 &lt;code&gt;note&lt;/code&gt;、&lt;code&gt;info&lt;/code&gt;、&lt;code&gt;tip&lt;/code&gt;、&lt;code&gt;important&lt;/code&gt;、&lt;code&gt;warning&lt;/code&gt;、&lt;code&gt;caution&lt;/code&gt;，以及可折叠的 &lt;code&gt;details&lt;/code&gt;。&lt;/p&gt;
&lt;h3&gt;note（带自定义标题）&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;写法&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;::: note 部署背景
空格形式接受普通的自定义标题，同时与参考语法保持兼容。
:::
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;渲染效果&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;::: note 部署背景
空格形式接受普通的自定义标题，同时与参考语法保持兼容。
:::&lt;/p&gt;
&lt;h3&gt;info&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;写法&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;:::info
信息块用于提供中性背景，帮助读者理解上下文。
:::
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;渲染效果&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;:::info
信息块用于提供中性背景，帮助读者理解上下文。
:::&lt;/p&gt;
&lt;h3&gt;tip（方括号标题 + 行内 Markdown）&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;写法&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;:::tip[已有的 **标签** 语法]
原始的方括号标签依然可用，且能包含行内 Markdown 强调。
:::
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;渲染效果&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;:::tip[已有的 &lt;strong&gt;标签&lt;/strong&gt; 语法]
原始的方括号标签依然可用，且能包含行内 Markdown 强调。
:::&lt;/p&gt;
&lt;h3&gt;important（GitHub Alert 语法）&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;写法&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;&amp;gt; [!IMPORTANT]
&amp;gt; GitHub Alert 语法进入同一个渲染器，因此既有文章保持统一的视觉语言。
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;渲染效果&lt;/strong&gt;&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;[!IMPORTANT]
GitHub Alert 语法进入同一个渲染器，因此既有文章保持统一的视觉语言。&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h3&gt;warning&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;写法&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;:::warning
运行生产构建前请检查环境变量。
:::
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;渲染效果&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;:::warning
运行生产构建前请检查环境变量。
:::&lt;/p&gt;
&lt;h3&gt;caution&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;写法&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;:::caution
不要在示例中发布凭据、本地配置或私钥。
:::
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;渲染效果&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;:::caution
不要在示例中发布凭据、本地配置或私钥。
:::&lt;/p&gt;
&lt;h2&gt;可折叠的 details&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;details&lt;/code&gt; 类型渲染为可折叠块，初始收起，适合放可选的长命令、排错步骤。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;写法&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;::: details 查看完整命令
该折叠块使用浏览器原生语义，无需客户端 JavaScript 也可键盘访问。

```powershell
npx.cmd astro check
pnpm.cmd build
```

- 初始为收起状态。
- 长代码可在自己的代码块内滚动。
- 窄屏下容器仍保持在文章宽度内。
:::
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;渲染效果&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;::: details 查看完整命令
该折叠块使用浏览器原生语义，无需客户端 JavaScript 也可键盘访问。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;npx.cmd astro check
pnpm.cmd build
&lt;/code&gt;&lt;/pre&gt;
&lt;ul&gt;
&lt;li&gt;初始为收起状态。&lt;/li&gt;
&lt;li&gt;长代码可在自己的代码块内滚动。&lt;/li&gt;
&lt;li&gt;窄屏下容器仍保持在文章宽度内。
:::&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;标题的两种写法&lt;/h2&gt;
&lt;pre&gt;&lt;code&gt;:::note[方括号标题]
内容
:::

::: warning 空格标题（Plume 兼容）
内容
:::
&lt;/code&gt;&lt;/pre&gt;
</content:encoded></item><item><title>行内语音朗读（Audio Reader）</title><link>https://blog.0v0.uno/posts/markdown-guide/audio-reader/</link><guid isPermaLink="true">https://blog.0v0.uno/posts/markdown-guide/audio-reader/</guid><description>用 Audio Reader 按需播放一小段日语动漫风格的神秘语音。</description><pubDate>Fri, 06 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;这几段简短的日语语音，仿佛取自某个动漫场景的边缘：一声调侃的呼唤、一句明快的问候、一声轻笑，还有几句来源不明的话。它们更像氛围样本而非对白字幕，所以让声音本身去传达含义吧。&lt;/p&gt;
&lt;p&gt;Audio Reader 让它们在你选择收听之前保持安静。每个播放按钮只在你按下后才加载并播放对应音频。&lt;/p&gt;
&lt;h2&gt;写法&lt;/h2&gt;
&lt;pre&gt;&lt;code&gt;:audio-reader[片段标题]{src=&quot;/assets/audio/文件名.wav&quot;}
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;渲染效果&lt;/h2&gt;
&lt;p&gt;把下面的播放按钮点开试听——音频文件放在内容仓的 &lt;code&gt;public/assets/audio/&lt;/code&gt; 下，引用时用站点根路径 &lt;code&gt;/assets/audio/...&lt;/code&gt;：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Baka&lt;/strong&gt;：:audio-reader[バカ]{src=&quot;/assets/audio/Baka.wav&quot;}&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Ciallo&lt;/strong&gt;：:audio-reader[Ciallo！！]{src=&quot;/assets/audio/Ciallo.wav&quot;}&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Ehe&lt;/strong&gt;：:audio-reader[一种打趣的语气]{src=&quot;/assets/audio/Ehe.wav&quot;}&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Imoi&lt;/strong&gt;：:audio-reader[イモい]{src=&quot;/assets/audio/Imoi.wav&quot;}&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Zako&lt;/strong&gt;：:audio-reader[雑魚じゃん、雑魚雑魚]{src=&quot;/assets/audio/Zako.wav&quot;}&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;对应的源码写法：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;- **Baka**：:audio-reader[バカ]{src=&quot;/assets/audio/Baka.wav&quot;}
- **Ciallo**：:audio-reader[Ciallo！！]{src=&quot;/assets/audio/Ciallo.wav&quot;}
- **Ehe**：:audio-reader[一种打趣的语气]{src=&quot;/assets/audio/Ehe.wav&quot;}
- **Imoi**：:audio-reader[イモい]{src=&quot;/assets/audio/Imoi.wav&quot;}
- **Zako**：:audio-reader[雑魚じゃん、雑魚雑魚]{src=&quot;/assets/audio/Zako.wav&quot;}
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;规则&lt;/h2&gt;
&lt;p&gt;&lt;code&gt;src&lt;/code&gt; 必须使用站点根路径或 HTTPS URL，且指令标签不能为空。非法或不完整的指令会保留为普通 Markdown，不会加载 Audio Reader 资源。&lt;/p&gt;
</content:encoded></item><item><title>Markdown 基础语法示例</title><link>https://blog.0v0.uno/posts/markdown-guide/basic-syntax/</link><guid isPermaLink="true">https://blog.0v0.uno/posts/markdown-guide/basic-syntax/</guid><description>Markdown 博客文章的基础语法示例。</description><pubDate>Fri, 06 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h1&gt;一级标题&lt;/h1&gt;
&lt;p&gt;段落之间用空行分隔。&lt;/p&gt;
&lt;p&gt;第二段。&lt;em&gt;斜体&lt;/em&gt;、&lt;strong&gt;加粗&lt;/strong&gt; 和 &lt;code&gt;等宽&lt;/code&gt;。无序列表
长这样：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;这一项&lt;/li&gt;
&lt;li&gt;那一项&lt;/li&gt;
&lt;li&gt;还有一项&lt;/li&gt;
&lt;/ul&gt;
&lt;blockquote&gt;
&lt;p&gt;引用块
长这样。&lt;/p&gt;
&lt;p&gt;可以跨多个段落，
如果你喜欢的话。&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;破折号用三个连字符表示。两个连字符表示范围（如&quot;第 12–14 章&quot;）。三个点 ... 会转为省略号。支持 Unicode。☺&lt;/p&gt;
&lt;h2&gt;二级标题&lt;/h2&gt;
&lt;p&gt;这是一个有序列表：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;第一项&lt;/li&gt;
&lt;li&gt;第二项&lt;/li&gt;
&lt;li&gt;第三项&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;下面是一个代码示例：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;# 重申一下……
for i in 1 .. 10 { do-something(i) }
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;如你所料，缩进 4 个空格。顺便，也可以用围栏代码块代替缩进：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;define foobar() {
    print &quot;欢迎来到风味之乡！&quot;;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;（这样复制粘贴更方便。）还可以给围栏块标注语言以启用语法高亮：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;import time
# 快，数到十！
for i in range(10):
    # （但别太快）
    time.sleep(0.5)
    print i
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;三级标题&lt;/h3&gt;
&lt;p&gt;这是一个嵌套列表：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;先准备这些食材：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;胡萝卜&lt;/li&gt;
&lt;li&gt;芹菜&lt;/li&gt;
&lt;li&gt;扁豆&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;烧一些水。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;把所有东西倒进锅里，按这个
算法操作：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt; 找到木勺
 揭开锅盖
 搅拌
 盖上锅盖
 把木勺危险地架在锅柄上
 等 10 分钟
 回到第一步（或关火）
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;别碰木勺，不然它会掉。&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;这是一个 &lt;a href=&quot;http://foo.bar&quot;&gt;网站链接&lt;/a&gt;，一个 &lt;a href=&quot;local-doc.html&quot;&gt;本地文档&lt;/a&gt;，以及一个指向本文&lt;a href=&quot;#%E4%BA%8C%E7%BA%A7%E6%A0%87%E9%A2%98&quot;&gt;某个标题的链接&lt;/a&gt;。这是一个脚注 &lt;a href=&quot;%E8%84%9A%E6%B3%A8%E5%86%85%E5%AE%B9%E5%86%99%E5%9C%A8%E8%BF%99%E9%87%8C%E3%80%82&quot;&gt;^1&lt;/a&gt;。&lt;/p&gt;
&lt;p&gt;表格可以这样写：&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;尺寸&lt;/th&gt;
&lt;th&gt;材质&lt;/th&gt;
&lt;th&gt;颜色&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;9&lt;/td&gt;
&lt;td&gt;皮革&lt;/td&gt;
&lt;td&gt;棕色&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;10&lt;/td&gt;
&lt;td&gt;麻帆布&lt;/td&gt;
&lt;td&gt;自然色&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;11&lt;/td&gt;
&lt;td&gt;玻璃&lt;/td&gt;
&lt;td&gt;透明&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;下面是一条分割线。&lt;/p&gt;
&lt;hr /&gt;
&lt;p&gt;这是一个定义列表：&lt;/p&gt;
&lt;p&gt;苹果
: 适合做苹果酱。
橙子
: 柑橘类！
番茄
: tomato 里没有 e。&lt;/p&gt;
&lt;p&gt;行内数学公式这样写：$\omega = d\phi / dt$。块级公式单独占一行，用双美元符号包裹：&lt;/p&gt;
&lt;p&gt;$$I = \int \rho R^{2} dV$$&lt;/p&gt;
&lt;p&gt;$$
\begin{equation*}
\pi
=3.1415926535
;8979323846;2643383279;5028841971;6939937510;5820974944
;5923078164;0628620899;8628034825;3421170679;\ldots
\end{equation*}
$$&lt;/p&gt;
&lt;p&gt;注意，任何标点符号都可以用反斜杠转义以原样显示，例如：`foo`、*bar* 等。&lt;/p&gt;
</content:encoded></item><item><title>Markdown 折叠面板</title><link>https://blog.0v0.uno/posts/markdown-guide/collapse-panels/</link><guid isPermaLink="true">https://blog.0v0.uno/posts/markdown-guide/collapse-panels/</guid><description>把可选的 Markdown 内容分组收纳进紧凑、无障碍的 M3E 折叠面板。</description><pubDate>Fri, 06 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;折叠面板把相关的可选细节收进一个紧凑分组。标题与正文保留行内和块级 Markdown，原生 disclosure 语义让每个面板无需客户端 JavaScript 即可使用。&lt;/p&gt;
&lt;p&gt;容器内&lt;strong&gt;只能有一个顶层无序列表&lt;/strong&gt;：每一项 = 一个标题段落 + 一个空行 + 正文内容。标题前缀 &lt;code&gt;:+&lt;/code&gt; 默认展开、&lt;code&gt;:-&lt;/code&gt; 默认折叠。&lt;/p&gt;
&lt;h2&gt;独立面板（默认）&lt;/h2&gt;
&lt;p&gt;各项独立开合，互不影响。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;写法&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;::: collapse
- **环境要求**

  使用 Node.js 26.13.0 或更高版本，安装包之前先启用 Corepack。

- :+ 安装依赖

  在仓库根目录运行工作区包命令。

  ```powershell
  pnpm.cmd install
  ```

- 校验命令

  构建生产产物前检查内容流水线。

  - `pnpm.cmd check:manifest`
  - `npx.cmd astro check`
:::
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;渲染效果&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;::: collapse&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;环境要求&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;使用 Node.js 26.13.0 或更高版本，安装包之前先启用 Corepack。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;:+ 安装依赖&lt;/p&gt;
&lt;p&gt;在仓库根目录运行工作区包命令。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;pnpm.cmd install
&lt;/code&gt;&lt;/pre&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;校验命令&lt;/p&gt;
&lt;p&gt;构建生产产物前检查内容流水线。&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;pnpm.cmd check:manifest&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;npx.cmd astro check&lt;/code&gt;
:::&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;手风琴模式（accordion）&lt;/h2&gt;
&lt;p&gt;加 &lt;code&gt;accordion&lt;/code&gt; 后同一时间只展开一项，打开另一项自动收起上一项。&lt;code&gt;expand&lt;/code&gt; 让首项默认展开（无 &lt;code&gt;:+&lt;/code&gt; 标记时）。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;写法&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;::: collapse accordion expand
- 这里的 `expand` 起什么作用？

  当没有任何 `:+` 标记时，让第一项初始展开。

- 标题能包含 Markdown 吗？

  可以。标题支持行内**强调**和 `code`，面板正文支持完整块级 Markdown。

- 窄屏下会怎样？

  内容内边距变紧凑，长文本换行，嵌入代码保留独立的横向滚动区。
:::
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;渲染效果&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;::: collapse accordion expand&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;这里的 &lt;code&gt;expand&lt;/code&gt; 起什么作用？&lt;/p&gt;
&lt;p&gt;当没有任何 &lt;code&gt;:+&lt;/code&gt; 标记时，让第一项初始展开。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;标题能包含 Markdown 吗？&lt;/p&gt;
&lt;p&gt;可以。标题支持行内&lt;strong&gt;强调&lt;/strong&gt;和 &lt;code&gt;code&lt;/code&gt;，面板正文支持完整块级 Markdown。&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;窄屏下会怎样？&lt;/p&gt;
&lt;p&gt;内容内边距变紧凑，长文本换行，嵌入代码保留独立的横向滚动区。
:::&lt;/p&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;参数与标记速查&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;写法&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;accordion&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;手风琴模式，一次只展开一项&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;expand&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;无 &lt;code&gt;:+&lt;/code&gt; 项时默认展开首项&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;项前 &lt;code&gt;:+&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;该项默认展开&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;项前 &lt;code&gt;:-&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;该项默认折叠（容器用 &lt;code&gt;expand&lt;/code&gt; 时覆盖）&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;也支持花括号写法 &lt;code&gt;:::collapse{accordion=true expand=true}&lt;/code&gt;，与空格写法等价。非法或混合格式的输入会保留为普通可读的 Markdown 列表。&lt;/p&gt;
</content:encoded></item><item><title>Markdown 内容注解</title><link>https://blog.0v0.uno/posts/markdown-guide/content-annotations/</link><guid isPermaLink="true">https://blog.0v0.uno/posts/markdown-guide/content-annotations/</guid><description>为文章添加紧凑、无障碍的补充说明，而不打断阅读流。</description><pubDate>Fri, 06 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;内容注解把补充背景贴近某个句子，又不直接塞进阅读流。点击那个小小的注解标记即可展开内容。定义行不会出现在正文里。&lt;/p&gt;
&lt;h2&gt;基础用法&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;写法&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;Astro 会预先渲染页面的大部分内容，只在**交互孤岛** [+islands] 需要交互时才为其水合。

[+islands]:
  孤岛是被静态 HTML 包围的可交互 UI 组件。这让默认页面保持轻量，又保留了局部的交互能力。
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;渲染效果&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;Astro 会预先渲染页面的大部分内容，只在&lt;strong&gt;交互孤岛&lt;/strong&gt; [+islands] 需要交互时才为其水合。&lt;/p&gt;
&lt;p&gt;[+islands]:
孤岛是被静态 HTML 包围的可交互 UI 组件。这让默认页面保持轻量，又保留了局部的交互能力。&lt;/p&gt;
&lt;h2&gt;富文本内容（Rich content）&lt;/h2&gt;
&lt;p&gt;定义里可以放段落、加粗、链接、列表和行内代码，正文句子照常连贯。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;写法&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;定义里可以包含段落、强调、链接、列表和行内代码 [+rich-note]，而周围句子正常延续。

[+rich-note]:
  **写作建议**

  - 首句保持自洽。
  - 读者可能需要原始出处时放链接。
  - 优先用简洁示例，比如 `client:visible`。

  完整模型见 [Astro 孤岛文档](https://docs.astro.build/en/concepts/islands/)。
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;渲染效果&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;定义里可以包含段落、强调、链接、列表和行内代码 &lt;a href=&quot;**%E5%86%99%E4%BD%9C%E5%BB%BA%E8%AE%AE**&quot;&gt;+rich-note&lt;/a&gt;，而周围句子正常延续。&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;首句保持自洽。&lt;/li&gt;
&lt;li&gt;读者可能需要原始出处时放链接。&lt;/li&gt;
&lt;li&gt;优先用简洁示例，比如 &lt;code&gt;client:visible&lt;/code&gt;。&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;完整模型见 &lt;a href=&quot;https://docs.astro.build/en/concepts/islands/&quot;&gt;Astro 孤岛文档&lt;/a&gt;。&lt;/p&gt;
&lt;h2&gt;同一标签多定义&lt;/h2&gt;
&lt;p&gt;复用同一标签写多行定义，标记弹层里会按序列出所有相关注解。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;写法&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;复用一个标签 [+review]，可在一个标记背后呈现一串相关注解。

[+review]: 先写会改变读者下一步行动的那个决定。
[+review]: 把实现证据与背景上下文分开。
[+review]: 删掉本该写进正文而非注解的细节。
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;渲染效果&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;复用一个标签 &lt;a href=&quot;%E5%85%88%E5%86%99%E4%BC%9A%E6%94%B9%E5%8F%98%E8%AF%BB%E8%80%85%E4%B8%8B%E4%B8%80%E6%AD%A5%E8%A1%8C%E5%8A%A8%E7%9A%84%E9%82%A3%E4%B8%AA%E5%86%B3%E5%AE%9A%E3%80%82&quot;&gt;+review&lt;/a&gt;，可在一个标记背后呈现一串相关注解。&lt;/p&gt;
&lt;h2&gt;未定义的引用&lt;/h2&gt;
&lt;p&gt;写了 &lt;code&gt;[+标签]&lt;/code&gt; 但没给定义时，只渲染为普通文本，不会生成空气泡控件。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;写法&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;这是一个未定义的引用 [+missing]，渲染为普通文本。
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;渲染效果&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;这是一个未定义的引用 [+missing]，渲染为普通文本。&lt;/p&gt;
</content:encoded></item><item><title>🔒 密码保护与文章加密演示</title><link>https://blog.0v0.uno/posts/markdown-guide/encrypted-demo/</link><guid isPermaLink="true">https://blog.0v0.uno/posts/markdown-guide/encrypted-demo/</guid><description>该文章内容已加密，请输入密码后查看。</description><pubDate>Fri, 06 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;&lt;em&gt;🔒 本文已加密保护，请访问博客网站输入密码阅读全文。&lt;/em&gt;&lt;/p&gt;</content:encoded></item><item><title>Shirone Markdown 增强：文件树与代码树</title><link>https://blog.0v0.uno/posts/markdown-guide/enhancements/</link><guid isPermaLink="true">https://blog.0v0.uno/posts/markdown-guide/enhancements/</guid><description>探索 Shirone 的文件树、代码树等自定义 Markdown 扩展与作者语法。</description><pubDate>Fri, 06 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;Shirone 提供一组主题专属的 Markdown 扩展与自定义语法容器。基于原生 unified AST 处理管线，所有扩展在构建期渲染为无障碍、语义化的 HTML，&lt;strong&gt;零客户端 JavaScript 水合开销&lt;/strong&gt;，并与 M3E 设计令牌完全对齐。&lt;/p&gt;
&lt;h2&gt;文件树&lt;/h2&gt;
&lt;p&gt;文件树把多级项目结构、源码层级和终端目录输出变成紧凑、可交互的树状视图，带自动扩展名图标、diff 高亮和可折叠分支。&lt;/p&gt;
&lt;h3&gt;1. 嵌套列表语法（&lt;code&gt;:::file-tree&lt;/code&gt;）&lt;/h3&gt;
&lt;p&gt;直接把文件层级写成 Markdown 嵌套列表时使用 &lt;code&gt;:::file-tree&lt;/code&gt; 块指令。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;:::file-tree{title=&quot;Shirone 源码树&quot;}
- src
  - components/
    - ++ Navigation.svelte # 新增组件
    - -- Button.astro # 移除组件
  - content
    - posts/
      - markdown-enhancements.md
  - layouts/
    - PostLayout.astro
  - plugins
    - markdown/
      - rehype-file-tree.mjs
  - styles
    - markdown/
      - trees.css
  - **content.config.ts** # 重要文件
- public/
  - favicon.svg
- package.json
:::
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::file-tree{title=&quot;Shirone 源码树&quot;}&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;src
&lt;ul&gt;
&lt;li&gt;components/
&lt;ul&gt;
&lt;li&gt;++ Navigation.svelte # 新增组件&lt;/li&gt;
&lt;li&gt;-- Button.astro # 移除组件&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;content
&lt;ul&gt;
&lt;li&gt;posts/
&lt;ul&gt;
&lt;li&gt;markdown-enhancements.md&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;layouts/
&lt;ul&gt;
&lt;li&gt;PostLayout.astro&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;plugins
&lt;ul&gt;
&lt;li&gt;markdown/
&lt;ul&gt;
&lt;li&gt;rehype-file-tree.mjs&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;styles
&lt;ul&gt;
&lt;li&gt;markdown/
&lt;ul&gt;
&lt;li&gt;trees.css&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;content.config.ts&lt;/strong&gt; # 重要文件&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;public/
&lt;ul&gt;
&lt;li&gt;favicon.svg&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;package.json
:::&lt;/li&gt;
&lt;/ul&gt;
&lt;h4&gt;写作规则与标记&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Diff 状态&lt;/strong&gt;：条目加 &lt;code&gt;++&lt;/code&gt; 前缀（绿底+徽标）或 &lt;code&gt;--&lt;/code&gt; 前缀（红底+删除线）可高亮变更。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;注释&lt;/strong&gt;：&lt;code&gt;#&lt;/code&gt; 后的文本渲染为低调的右对齐行内注释。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;强调&lt;/strong&gt;：用 &lt;code&gt;**加粗**&lt;/code&gt; 包裹名称，让关键文件更醒目。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;可折叠目录&lt;/strong&gt;：由嵌套列表推断出的目录默认展开。尾随斜杠（如 &lt;code&gt;components/&lt;/code&gt;）会创建初始折叠的目录，读者可点击或键盘展开。&lt;/li&gt;
&lt;/ul&gt;
&lt;hr /&gt;
&lt;h3&gt;2. 终端输出语法（&lt;code&gt;```file-tree&lt;/code&gt;）&lt;/h3&gt;
&lt;p&gt;已有 &lt;code&gt;tree&lt;/code&gt; 等命令行工具生成的目录文本时，直接粘进 &lt;code&gt;file-tree&lt;/code&gt; 围栏代码块。Unicode 分支符（&lt;code&gt;├──&lt;/code&gt;、&lt;code&gt;└──&lt;/code&gt;、&lt;code&gt;│&lt;/code&gt;）和 ASCII 分支都能自动解析。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;```file-tree title=&quot;构建产物&quot; icon=&quot;simple&quot;
dist
├── _astro/
│   ├── index.css
│   └── page.js
└── favicon.ico
```
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;dist
├── _astro/
│   ├── index.css
│   └── page.js
└── favicon.ico
&lt;/code&gt;&lt;/pre&gt;
&lt;h4&gt;配置项&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;title=&quot;字符串&quot;&lt;/code&gt;：设置树的自定义标题与无障碍标签。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;icon=&quot;colored&quot; | &quot;simple&quot;&lt;/code&gt;：在多彩扩展名图标（&lt;code&gt;colored&lt;/code&gt;，默认）与极简单色图标（&lt;code&gt;simple&lt;/code&gt;）之间选择。&lt;/li&gt;
&lt;/ul&gt;
&lt;hr /&gt;
&lt;h2&gt;代码树&lt;/h2&gt;
&lt;p&gt;交互式代码树左侧是多级文件导航，右侧即时切换代码面板，为多文件示例、模块或整目录走查提供 IDE 般的阅读体验。&lt;/p&gt;
&lt;h3&gt;1. 容器语法（&lt;code&gt;:::code-tree&lt;/code&gt;）&lt;/h3&gt;
&lt;p&gt;在 &lt;code&gt;:::code-tree&lt;/code&gt; 块指令里组合多个围栏代码块，每个代码块用 &lt;code&gt;title=&quot;路径/文件&quot;&lt;/code&gt; 指定路径。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;:::code-tree{title=&quot;Shirone 组件示例&quot; height=&quot;380px&quot; entry=&quot;src/Button.svelte&quot;}
```svelte title=&quot;src/Button.svelte&quot;
&amp;lt;script lang=&quot;ts&quot;&amp;gt;
  let { label = &quot;点击我&quot; } = $props();
&amp;lt;/script&amp;gt;

&amp;lt;button class=&quot;m3-btn&quot;&amp;gt;{label}&amp;lt;/button&amp;gt;
```

```stylus title=&quot;src/styles/button.styl&quot;
.m3-btn
  background: var(--primary)
  color: var(--on-primary)
  border-radius: var(--shape-corner-m)
```

```json title=&quot;package.json&quot;
{
  &quot;name&quot;: &quot;button-demo&quot;,
  &quot;version&quot;: &quot;1.0.0&quot;
}
```
:::
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::code-tree{title=&quot;Shirone 组件示例&quot; height=&quot;380px&quot; entry=&quot;src/Button.svelte&quot;}&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;&amp;lt;script lang=&quot;ts&quot;&amp;gt;
  let { label = &quot;点击我&quot; } = $props();
&amp;lt;/script&amp;gt;

&amp;lt;button class=&quot;m3-btn&quot;&amp;gt;{label}&amp;lt;/button&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;.m3-btn
  background: var(--primary)
  color: var(--on-primary)
  border-radius: var(--shape-corner-m)
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;{
  &quot;name&quot;: &quot;button-demo&quot;,
  &quot;version&quot;: &quot;1.0.0&quot;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::&lt;/p&gt;
&lt;h4&gt;配置与标记&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;title=&quot;字符串&quot;&lt;/code&gt;：设置代码树的标题与无障碍标签。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;height=&quot;字符串&quot;&lt;/code&gt;：设置桌面视图高度（默认 &lt;code&gt;420px&lt;/code&gt;，如 &lt;code&gt;380px&lt;/code&gt;、&lt;code&gt;26rem&lt;/code&gt;）。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;entry=&quot;文件路径&quot;&lt;/code&gt;：指定首次加载时激活的文件。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;icon=&quot;colored&quot; | &quot;simple&quot;&lt;/code&gt;：在彩色或极简单色文件图标间切换。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;:active&lt;/code&gt;：在任意围栏代码块上标 &lt;code&gt;:active&lt;/code&gt;，指定其为默认激活标签页。&lt;/li&gt;
&lt;/ul&gt;
&lt;hr /&gt;
&lt;h3&gt;2. 本地目录自动引入（&lt;code&gt;@[code-tree]&lt;/code&gt;）&lt;/h3&gt;
&lt;p&gt;直接指向工作区内任意本地目录路径，构建期自动扫描并生成交互式代码树，无需手动复制文件内容。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;@[code-tree title=&quot;番剧工具函数&quot; entry=&quot;status.ts&quot;](/src/utils/anime)
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;@&lt;a href=&quot;/src/config&quot;&gt;code-tree title=&quot;站点配置&quot; entry=&quot;siteConfig.ts&quot;&lt;/a&gt;&lt;/p&gt;
</content:encoded></item><item><title>Expressive Code 代码块</title><link>https://blog.0v0.uno/posts/markdown-guide/expressive-code/</link><guid isPermaLink="true">https://blog.0v0.uno/posts/markdown-guide/expressive-code/</guid><description>Markdown 中使用 Expressive Code 的代码块效果一览。</description><pubDate>Fri, 06 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;本文展示基于 &lt;a href=&quot;https://expressive-code.com/&quot;&gt;Expressive Code&lt;/a&gt; 的代码块效果。示例参考官方文档，可查阅其了解更多细节。&lt;/p&gt;
&lt;h2&gt;语法高亮&lt;/h2&gt;
&lt;p&gt;&lt;a href=&quot;https://expressive-code.com/key-features/syntax-highlighting/&quot;&gt;语法高亮&lt;/a&gt;&lt;/p&gt;
&lt;h3&gt;常规高亮&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;console.log(&apos;这段代码会被语法高亮&apos;)
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;渲染 ANSI 转义序列&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;ANSI colors:
- Regular: [31mRed[0m [32mGreen[0m [33mYellow[0m [34mBlue[0m [35mMagenta[0m [36mCyan[0m
- Bold:    [1;31mRed[0m [1;32mGreen[0m [1;33mYellow[0m [1;34mBlue[0m [1;35mMagenta[0m [1;36mCyan[0m
- Dimmed:  [2;31mRed[0m [2;32mGreen[0m [2;33mYellow[0m [2;34mBlue[0m [2;35mMagenta[0m [2;36mCyan[0m

256 colors (showing colors 160-177):
[38;5;160m160 [38;5;161m161 [38;5;162m162 [38;5;163m163 [38;5;164m164 [38;5;165m165[0m
[38;5;166m166 [38;5;167m167 [38;5;168m168 [38;5;169m169 [38;5;170m170 [38;5;171m171[0m
[38;5;172m172 [38;5;173m173 [38;5;174m174 [38;5;175m175 [38;5;176m176 [38;5;177m177[0m

Full RGB colors:
[38;2;34;139;34mForestGreen - RGB(34, 139, 34)[0m

Text formatting: [1mBold[0m [2mDimmed[0m [3mItalic[0m [4mUnderline[0m
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;编辑器与终端框架&lt;/h2&gt;
&lt;p&gt;&lt;a href=&quot;https://expressive-code.com/key-features/frames/&quot;&gt;编辑器与终端框架&lt;/a&gt;&lt;/p&gt;
&lt;h3&gt;代码编辑器框架&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;console.log(&apos;标题属性示例&apos;)
&lt;/code&gt;&lt;/pre&gt;
&lt;hr /&gt;
&lt;pre&gt;&lt;code&gt;&amp;lt;!-- src/content/index.html --&amp;gt;
&amp;lt;div&amp;gt;文件名注释示例&amp;lt;/div&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;终端框架&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;echo &quot;这个终端框架没有标题&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;hr /&gt;
&lt;pre&gt;&lt;code&gt;Write-Output &quot;这个有标题！&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;覆盖框架类型&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;echo &quot;看，没有外框！&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;hr /&gt;
&lt;pre&gt;&lt;code&gt;# 不覆盖的话，这本该是终端框架
function Watch-Tail { Get-Content -Tail 20 -Wait $args }
New-Alias tail Watch-Tail
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;文本与行标记&lt;/h2&gt;
&lt;p&gt;&lt;a href=&quot;https://expressive-code.com/key-features/text-markers/&quot;&gt;文本与行标记&lt;/a&gt;&lt;/p&gt;
&lt;h3&gt;标记整行与行范围&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;// 第 1 行 - 按行号标记
// 第 2 行
// 第 3 行
// 第 4 行 - 按行号标记
// 第 5 行
// 第 6 行
// 第 7 行 - 按范围 &quot;7-8&quot; 标记
// 第 8 行 - 按范围 &quot;7-8&quot; 标记
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;选择行标记类型（mark、ins、del）&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;function demo() {
  console.log(&apos;这行被标记为删除&apos;)
  // 本行和下一行被标记为新增
  console.log(&apos;这是第二行新增&apos;)

  return &apos;这行使用默认的中性标记类型&apos;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;给行标记加标签&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;// labeled-line-markers.jsx
&amp;lt;button
  role=&quot;button&quot;
  {...props}
  value={value}
  className={buttonClassName}
  disabled={disabled}
  active={active}
&amp;gt;
  {children &amp;amp;&amp;amp;
    !active &amp;amp;&amp;amp;
    (typeof children === &apos;string&apos; ? &amp;lt;span&amp;gt;{children}&amp;lt;/span&amp;gt; : children)}
&amp;lt;/button&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;在独立行上放长标签&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;// labeled-line-markers.jsx
&amp;lt;button
  role=&quot;button&quot;
  {...props}

  value={value}
  className={buttonClassName}

  disabled={disabled}
  active={active}
&amp;gt;

  {children &amp;amp;&amp;amp;
    !active &amp;amp;&amp;amp;
    (typeof children === &apos;string&apos; ? &amp;lt;span&amp;gt;{children}&amp;lt;/span&amp;gt; : children)}
&amp;lt;/button&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;使用 diff 风格语法&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;+这行会被标记为新增
-这行会被标记为删除
这是普通的一行
&lt;/code&gt;&lt;/pre&gt;
&lt;hr /&gt;
&lt;pre&gt;&lt;code&gt;--- a/README.md
+++ b/README.md
@@ -1,3 +1,4 @@
+这是一个真实的 diff 文件
-所有内容都保持不变
 空白也不会被移除
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;diff 语法 + 语法高亮组合&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;  function thisIsJavaScript() {
    // 整个块按 JavaScript 高亮，
    // 同时还能加 diff 标记！
-   console.log(&apos;要移除的旧代码&apos;)
+   console.log(&apos;闪亮的新代码！&apos;)
  }
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;标记行内特定文本&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;function demo() {
  // 标记行内任意给定文本
  return &apos;支持匹配多处相同文本&apos;;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;正则表达式&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;console.log(&apos;单词 yes 和 yep 都会被标记。&apos;)
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;转义正斜杠&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;echo &quot;Test&quot; &amp;gt; /home/test.txt
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;选择行内标记类型（mark、ins、del）&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;function demo() {
  console.log(&apos;这里有 inserted 和 deleted 两种标记类型&apos;);
  // return 语句用默认标记类型
  return true;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;自动换行&lt;/h2&gt;
&lt;p&gt;&lt;a href=&quot;https://expressive-code.com/key-features/word-wrap/&quot;&gt;自动换行&lt;/a&gt;&lt;/p&gt;
&lt;h3&gt;按块配置换行&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;// 开启换行的示例
function getLongString() {
  return &apos;这是一个非常长的字符串，除非容器极宽否则很可能放不下可用空间&apos;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;hr /&gt;
&lt;pre&gt;&lt;code&gt;// 关闭换行的示例
function getLongString() {
  return &apos;这是一个非常长的字符串，除非容器极宽否则很可能放不下可用空间&apos;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;配置换行缩进&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;// preserveIndent 示例（默认开启）
function getLongString() {
  return &apos;这是一个非常长的字符串，除非容器极宽否则很可能放不下可用空间&apos;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;hr /&gt;
&lt;pre&gt;&lt;code&gt;// preserveIndent=false 示例
function getLongString() {
  return &apos;这是一个非常长的字符串，除非容器极宽否则很可能放不下可用空间&apos;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;可折叠区域&lt;/h2&gt;
&lt;p&gt;&lt;a href=&quot;https://expressive-code.com/plugins/collapsible-sections/&quot;&gt;可折叠区域&lt;/a&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;// 这些样板初始化代码会被折叠
import { someBoilerplateEngine } from &apos;@example/some-boilerplate&apos;
import { evenMoreBoilerplate } from &apos;@example/even-more-boilerplate&apos;

const engine = someBoilerplateEngine(evenMoreBoilerplate())

// 这部分默认可见
engine.doSomething(1, 2, 3, calcFn)

function calcFn() {
  // 可以有多个折叠区域
  const a = 1
  const b = 2
  const c = a + b

  // 这行保持可见
  console.log(`计算结果: ${a} + ${b} = ${c}`)
  return c
}

// 从这里到块尾的代码会再次折叠
engine.closeConnection()
engine.freeMemory()
engine.shutdown({ reason: &apos;样板代码示例结束&apos; })
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;行号&lt;/h2&gt;
&lt;p&gt;&lt;a href=&quot;https://expressive-code.com/plugins/line-numbers/&quot;&gt;行号&lt;/a&gt;&lt;/p&gt;
&lt;h3&gt;按块显示行号&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;// 这个代码块会显示行号
console.log(&apos;来自第 2 行的问候！&apos;)
console.log(&apos;我在第 3 行&apos;)
&lt;/code&gt;&lt;/pre&gt;
&lt;hr /&gt;
&lt;pre&gt;&lt;code&gt;// 这个块关闭了行号
console.log(&apos;你好？&apos;)
console.log(&apos;请问我在第几行？&apos;)
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;修改起始行号&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;console.log(&apos;来自第 5 行的问候！&apos;)
console.log(&apos;我在第 6 行&apos;)
&lt;/code&gt;&lt;/pre&gt;
</content:encoded></item><item><title>Markdown 扩展特性</title><link>https://blog.0v0.uno/posts/markdown-guide/extended-features/</link><guid isPermaLink="true">https://blog.0v0.uno/posts/markdown-guide/extended-features/</guid><description>GitHub 仓库卡片、提示容器、剧透与图片宽度等扩展特性。</description><pubDate>Fri, 06 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;h2&gt;GitHub 仓库卡片&lt;/h2&gt;
&lt;p&gt;可添加链接到 GitHub 仓库的动态卡片，页面加载时从 GitHub API 拉取仓库信息。&lt;/p&gt;
&lt;p&gt;::github{repo=&quot;Fabrizz/MMM-OnSpotify&quot;}&lt;/p&gt;
&lt;p&gt;用 &lt;code&gt;::github{repo=&quot;&amp;lt;owner&amp;gt;/&amp;lt;repo&amp;gt;&quot;}&lt;/code&gt; 创建仓库卡片。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;::github{repo=&quot;saicaca/fuwari&quot;}
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;Mermaid 图表&lt;/h2&gt;
&lt;p&gt;围栏 &lt;code&gt;mermaid&lt;/code&gt; 代码块会渲染为图表，并跟随当前配色方案。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;flowchart LR
    accTitle: Markdown 渲染流程
    accDescr: Markdown 源码被转换为语义化 HTML，再增强为带主题的 SVG 图表。
    A[Markdown 源码] --&amp;gt; B[Astro 内容管线]
    B --&amp;gt; C[语义化 HTML]
    C --&amp;gt; D[带主题的图表]
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;提示容器&lt;/h2&gt;
&lt;p&gt;支持以下类型：&lt;code&gt;note&lt;/code&gt; &lt;code&gt;tip&lt;/code&gt; &lt;code&gt;important&lt;/code&gt; &lt;code&gt;warning&lt;/code&gt; &lt;code&gt;caution&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;:::note
即使用户只是快速浏览，也应留意这些信息。
:::&lt;/p&gt;
&lt;p&gt;:::tip
帮助用户更顺利完成操作的可选信息。
:::&lt;/p&gt;
&lt;p&gt;:::important
用户成功所必需的关键信息。
:::&lt;/p&gt;
&lt;p&gt;:::warning
因潜在风险而需要用户立即注意的重要内容。
:::&lt;/p&gt;
&lt;p&gt;:::caution
某个操作可能带来的负面后果。
:::&lt;/p&gt;
&lt;h3&gt;基础语法&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;:::note
即使用户只是快速浏览，也应留意这些信息。
:::

:::tip
帮助用户更顺利完成操作的可选信息。
:::
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;自定义标题&lt;/h3&gt;
&lt;p&gt;提示容器的标题可以自定义。&lt;/p&gt;
&lt;p&gt;:::note[我的自定义标题]
这是一条带自定义标题的备注。
:::&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;:::note[我的自定义标题]
这是一条带自定义标题的备注。
:::
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;GitHub 语法&lt;/h3&gt;
&lt;blockquote&gt;
&lt;p&gt;[!TIP]
也支持 &lt;a href=&quot;https://github.com/orgs/community/discussions/16925&quot;&gt;GitHub 语法&lt;/a&gt;。&lt;/p&gt;
&lt;/blockquote&gt;
&lt;pre&gt;&lt;code&gt;&amp;gt; [!NOTE]
&amp;gt; 同样支持 GitHub 语法。

&amp;gt; [!TIP]
&amp;gt; 同样支持 GitHub 语法。
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;剧透&lt;/h3&gt;
&lt;p&gt;可以给文本加剧透黑幕，黑幕内也支持 &lt;strong&gt;Markdown&lt;/strong&gt; 语法。&lt;/p&gt;
&lt;p&gt;这段内容 :spoiler[被隐藏了 &lt;strong&gt;ayyy&lt;/strong&gt;]！&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;这段内容 :spoiler[被隐藏了 **ayyy**]！
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;图片宽度与图注&lt;/h2&gt;
&lt;p&gt;独占一行的图片，可在 alt 文本里加可选的 &lt;code&gt;w-N%&lt;/code&gt; 宽度令牌，并用 Markdown title 在图片下方渲染居中的图注。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;![图片描述 w-50%](./image.webp &quot;可见图注&quot;)
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;有效宽度范围 &lt;code&gt;w-1%&lt;/code&gt; 到 &lt;code&gt;w-100%&lt;/code&gt;；非法令牌会留在 alt 文本里。宽度与图注相互独立——只有 title 也会产生图注。&lt;/p&gt;
</content:encoded></item><item><title>Markdown 字段卡片</title><link>https://blog.0v0.uno/posts/markdown-guide/fields/</link><guid isPermaLink="true">https://blog.0v0.uno/posts/markdown-guide/fields/</guid><description>API 与组件参数文档的结构化卡片。</description><pubDate>Fri, 06 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;当若干相关选项同属一个 API 或组件时，用 &lt;code&gt;field-group&lt;/code&gt; 把它们排成整齐的卡片。每个示例下面都先给&lt;strong&gt;写法&lt;/strong&gt;（源码），再给&lt;strong&gt;渲染效果&lt;/strong&gt;。&lt;/p&gt;
&lt;h2&gt;基础组合&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;写法&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;:::: field-group

::: field tex
@type object
@optional

TeX 解析器配置项。
:::

::: field output
@type `&apos;svg&apos; | &apos;chtml&apos;`
@default `&apos;svg&apos;`
@optional

输出格式，SVG 或通用 HTML。
:::

::::
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;渲染效果&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;:::: field-group&lt;/p&gt;
&lt;p&gt;::: field tex
@type object
@optional&lt;/p&gt;
&lt;p&gt;TeX 解析器配置项。
:::&lt;/p&gt;
&lt;p&gt;::: field output
@type &lt;code&gt;&apos;svg&apos; | &apos;chtml&apos;&lt;/code&gt;
@default &lt;code&gt;&apos;svg&apos;&lt;/code&gt;
@optional&lt;/p&gt;
&lt;p&gt;输出格式，SVG 或通用 HTML。
:::&lt;/p&gt;
&lt;p&gt;::::&lt;/p&gt;
&lt;h2&gt;必填 / 可选 / 废弃状态&lt;/h2&gt;
&lt;p&gt;必填、可选、废弃状态可混在同一组。默认值与类型分开标注，便于快速扫读。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;写法&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;:::: field-group

::: field title
@type string
@required

组件的可见标题。该值显示在页面头部，应足够简短以便快速扫读。
:::

::: field disabled
@type boolean
@default `false`
@optional

控件是否初始为禁用状态。
:::

::: field locale
@type `&apos;en&apos; | &apos;zh-CN&apos; | &apos;ja-JP&apos;`
@default `&apos;en&apos;`
@optional

用于格式化日期、数字和无障碍标签的语言区域。
:::

::::
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;渲染效果&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;:::: field-group&lt;/p&gt;
&lt;p&gt;::: field title
@type string
@required&lt;/p&gt;
&lt;p&gt;组件的可见标题。该值显示在页面头部，应足够简短以便快速扫读。
:::&lt;/p&gt;
&lt;p&gt;::: field disabled
@type boolean
@default &lt;code&gt;false&lt;/code&gt;
@optional&lt;/p&gt;
&lt;p&gt;控件是否初始为禁用状态。
:::&lt;/p&gt;
&lt;p&gt;::: field locale
@type &lt;code&gt;&apos;en&apos; | &apos;zh-CN&apos; | &apos;ja-JP&apos;&lt;/code&gt;
@default &lt;code&gt;&apos;en&apos;&lt;/code&gt;
@optional&lt;/p&gt;
&lt;p&gt;用于格式化日期、数字和无障碍标签的语言区域。
:::&lt;/p&gt;
&lt;p&gt;::::&lt;/p&gt;
&lt;h2&gt;富文本描述&lt;/h2&gt;
&lt;p&gt;描述是普通 Markdown。元数据行之后仍可用链接、强调、列表和行内代码。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;写法&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;:::: field-group

::: field render
@type `(value: unknown) =&amp;gt; string`
@required

把数据值渲染为最终输出。回调应返回**安全字符串**，可使用 `formatValue` 辅助函数。

- 保持渲染确定性。
- 避免在回调内发起网络请求。
:::

::: field retries
@type number
@default `3`
@optional

请求被判定失败前的最大尝试次数。
:::

::: field legacyMode
@type boolean
@deprecated

为向后兼容保留。新接入应改用 `compatibility`。
:::

::::
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;渲染效果&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;:::: field-group&lt;/p&gt;
&lt;p&gt;::: field render
@type &lt;code&gt;(value: unknown) =&amp;gt; string&lt;/code&gt;
@required&lt;/p&gt;
&lt;p&gt;把数据值渲染为最终输出。回调应返回&lt;strong&gt;安全字符串&lt;/strong&gt;，可使用 &lt;code&gt;formatValue&lt;/code&gt; 辅助函数。&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;保持渲染确定性。&lt;/li&gt;
&lt;li&gt;避免在回调内发起网络请求。
:::&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;::: field retries
@type number
@default &lt;code&gt;3&lt;/code&gt;
@optional&lt;/p&gt;
&lt;p&gt;请求被判定失败前的最大尝试次数。
:::&lt;/p&gt;
&lt;p&gt;::: field legacyMode
@type boolean
@deprecated&lt;/p&gt;
&lt;p&gt;为向后兼容保留。新接入应改用 &lt;code&gt;compatibility&lt;/code&gt;。
:::&lt;/p&gt;
&lt;p&gt;::::&lt;/p&gt;
&lt;h2&gt;独立字段&lt;/h2&gt;
&lt;p&gt;只记录一个选项时，可不包组直接在示例或代码块旁使用单字段。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;写法&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;::: field format
@type `&apos;short&apos; | &apos;long&apos;`
@default `&apos;short&apos;`
@optional

控制结果的格式化方式。
:::
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;渲染效果&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;::: field format
@type &lt;code&gt;&apos;short&apos; | &apos;long&apos;&lt;/code&gt;
@default &lt;code&gt;&apos;short&apos;&lt;/code&gt;
@optional&lt;/p&gt;
&lt;p&gt;控制结果的格式化方式。
:::&lt;/p&gt;
&lt;h2&gt;元数据标签速查&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;标签&lt;/th&gt;
&lt;th&gt;作用&lt;/th&gt;
&lt;th&gt;渲染表现&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;@type&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;数据类型&lt;/td&gt;
&lt;td&gt;代码令牌&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;@default&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;默认取值&lt;/td&gt;
&lt;td&gt;代码令牌&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;@required&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;必填&lt;/td&gt;
&lt;td&gt;状态徽标&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;@optional&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;可选&lt;/td&gt;
&lt;td&gt;状态徽标&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;@deprecated&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;废弃&lt;/td&gt;
&lt;td&gt;状态徽标&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;ul&gt;
&lt;li&gt;元数据之后的任何普通 Markdown 都会成为字段描述。&lt;/li&gt;
&lt;li&gt;未知的 &lt;code&gt;@标签&lt;/code&gt; 会作为描述文本保留，而不是被丢弃。&lt;/li&gt;
&lt;/ul&gt;
</content:encoded></item><item><title>Frontmatter 元数据字段说明</title><link>https://blog.0v0.uno/posts/markdown-guide/frontmatter/</link><guid isPermaLink="true">https://blog.0v0.uno/posts/markdown-guide/frontmatter/</guid><description>Shirone 文章 Frontmatter 全部字段的含义、写法与行为说明。</description><pubDate>Fri, 06 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;每篇文章开头用三条横线 &lt;code&gt;---&lt;/code&gt; 包裹一段 YAML，称为 &lt;strong&gt;Frontmatter&lt;/strong&gt;，用来声明文章的标题、日期、分类、行为等元数据。&lt;/p&gt;
&lt;h2&gt;完整字段模板&lt;/h2&gt;
&lt;pre&gt;&lt;code&gt;---
# ── 必填 ──────────────────────────────
title: &quot;文章标题&quot;                    # 文章主标题
published: 2026-08-27               # 发布日期（YYYY-MM-DD）

# ── 时间与更新 ─────────────────────────
publishedAt: 2026-08-27T10:30:00+08:00  # 精确发布时间戳（同日多篇排序用）
updated: 2026-11-06                 # 最后更新日期
updatedAt: 2026-11-06T15:45:00+08:00    # 精确更新时间戳

# ── 摘要与封面 ─────────────────────────
description: &quot;文章摘要，用于卡片和 SEO&quot;   # 留空自动截取正文前段
image: &quot;./image.png&quot;                # 封面图（相对路径或外链）

# ── 分类与标签 ─────────────────────────
category: &quot;使用指南&quot;                  # 单分类
tags:                               # 多标签
  - &quot;Shirone&quot;
  - &quot;Markdown&quot;

# ── 行为控制 ─────────────────────────
pinned: true                        # 置顶到列表最前（默认 false）
draft: false                        # 草稿，true 时不进生产构建（默认 false）
comment: true                       # 开启评论区（默认 true）

# ── 系列关联 ─────────────────────────
series: &quot;starter-guide&quot;             # 所属系列 slug，对应 content/series/&amp;lt;slug&amp;gt;.md
seriesOrder: 1                      # 系列内排序序号（缺省按发布日期排）

# ── 加密 ────────────────────────────
encrypted: true                     # 标记文章加密
password: &quot;shirone-secret&quot;          # 解锁密码（设置后 encrypted 隐式为 true）
passwordHint: &quot;提示语&quot;               # 密码输入框下方提示
hideHomeContent: true               # 首页/归档/RSS 隐藏摘要与字数

# ── 其他 ────────────────────────────
lang: &quot;zh_CN&quot;                       # 文章语言（默认取站点语言）
---
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;字段逐项说明&lt;/h2&gt;
&lt;h3&gt;必填字段&lt;/h3&gt;
&lt;p&gt;:::: field-group&lt;/p&gt;
&lt;p&gt;::: field title
@type string
@required&lt;/p&gt;
&lt;p&gt;文章主标题，显示在文章页顶部、列表卡片与浏览器标签页。
:::&lt;/p&gt;
&lt;p&gt;::: field published
@type &lt;code&gt;YYYY-MM-DD&lt;/code&gt;
@required&lt;/p&gt;
&lt;p&gt;发布日期。文章按此日期倒序排列，也用于归档页分组。
:::&lt;/p&gt;
&lt;p&gt;::::&lt;/p&gt;
&lt;h3&gt;时间与更新&lt;/h3&gt;
&lt;p&gt;:::: field-group&lt;/p&gt;
&lt;p&gt;::: field publishedAt
@type ISO 8601 时间戳
@optional&lt;/p&gt;
&lt;p&gt;精确发布时间（含时区）。同一天发布多篇时用于精准排序；填写后其日历日期必须与 &lt;code&gt;published&lt;/code&gt; 一致，否则构建报错。
:::&lt;/p&gt;
&lt;p&gt;::: field updated
@type &lt;code&gt;YYYY-MM-DD&lt;/code&gt;
@optional&lt;/p&gt;
&lt;p&gt;最后更新日期。设置后文章页会显示&quot;最后更新&quot;信息。
:::&lt;/p&gt;
&lt;p&gt;::: field updatedAt
@type ISO 8601 时间戳
@optional&lt;/p&gt;
&lt;p&gt;精确更新时间戳，配合 &lt;code&gt;updated&lt;/code&gt; 使用。
:::&lt;/p&gt;
&lt;p&gt;::::&lt;/p&gt;
&lt;h3&gt;摘要与封面&lt;/h3&gt;
&lt;p&gt;:::: field-group&lt;/p&gt;
&lt;p&gt;::: field description
@type string
@optional&lt;/p&gt;
&lt;p&gt;文章摘要，用于列表卡片简介与搜索引擎摘要。留空时自动截取正文前段。
:::&lt;/p&gt;
&lt;p&gt;::: field image
@type string
@optional&lt;/p&gt;
&lt;p&gt;文章封面图。支持相对路径（如 &lt;code&gt;./image.png&lt;/code&gt;，与文章同目录，构建期自动优化）或网络外链。
:::&lt;/p&gt;
&lt;p&gt;::::&lt;/p&gt;
&lt;h3&gt;分类与标签&lt;/h3&gt;
&lt;p&gt;:::: field-group&lt;/p&gt;
&lt;p&gt;::: field category
@type string
@optional&lt;/p&gt;
&lt;p&gt;文章所属分类，&lt;strong&gt;只能填一个&lt;/strong&gt;。归档与分类页按它分组。
:::&lt;/p&gt;
&lt;p&gt;::: field tags
@type string[]
@optional&lt;/p&gt;
&lt;p&gt;标签列表，&lt;strong&gt;可填多个&lt;/strong&gt;。用于标签页聚合与相关文章推荐。
:::&lt;/p&gt;
&lt;p&gt;::::&lt;/p&gt;
&lt;h3&gt;行为控制&lt;/h3&gt;
&lt;p&gt;:::: field-group&lt;/p&gt;
&lt;p&gt;::: field pinned
@type boolean
@default &lt;code&gt;false&lt;/code&gt;
@optional&lt;/p&gt;
&lt;p&gt;设为 &lt;code&gt;true&lt;/code&gt; 时文章置顶到列表最前，不受发布日期排序影响。
:::&lt;/p&gt;
&lt;p&gt;::: field draft
@type boolean
@default &lt;code&gt;false&lt;/code&gt;
@optional&lt;/p&gt;
&lt;p&gt;设为 &lt;code&gt;true&lt;/code&gt; 时文章为草稿，&lt;strong&gt;不进入生产构建&lt;/strong&gt;，仅本地开发可见。
:::&lt;/p&gt;
&lt;p&gt;::: field comment
@type boolean
@default &lt;code&gt;true&lt;/code&gt;
@optional&lt;/p&gt;
&lt;p&gt;是否开启本篇文章的评论区。
:::&lt;/p&gt;
&lt;p&gt;::::&lt;/p&gt;
&lt;h3&gt;系列关联&lt;/h3&gt;
&lt;p&gt;:::: field-group&lt;/p&gt;
&lt;p&gt;::: field series
@type string
@optional&lt;/p&gt;
&lt;p&gt;所属系列的 slug，对应 &lt;code&gt;content/series/&amp;lt;slug&amp;gt;.md&lt;/code&gt;。声明后文章页出现系列导航（&quot;第 X/共 N 篇&quot;、上/下一篇）。
:::&lt;/p&gt;
&lt;p&gt;::: field seriesOrder
@type number
@optional&lt;/p&gt;
&lt;p&gt;系列内排序序号。缺省时按发布日期排序。
:::&lt;/p&gt;
&lt;p&gt;::::&lt;/p&gt;
&lt;h3&gt;加密&lt;/h3&gt;
&lt;p&gt;:::: field-group&lt;/p&gt;
&lt;p&gt;::: field encrypted
@type boolean
@default &lt;code&gt;false&lt;/code&gt;
@optional&lt;/p&gt;
&lt;p&gt;显式标记文章为加密。设置了 &lt;code&gt;password&lt;/code&gt; 时隐式为 &lt;code&gt;true&lt;/code&gt;。
:::&lt;/p&gt;
&lt;p&gt;::: field password
@type string
@required（加密时）&lt;/p&gt;
&lt;p&gt;前端加密的解锁密码。构建期加密、运行期解密，访客输入正确密码才能阅读。
:::&lt;/p&gt;
&lt;p&gt;::: field passwordHint
@type string
@optional&lt;/p&gt;
&lt;p&gt;显示在密码输入框下方的提示语。
:::&lt;/p&gt;
&lt;p&gt;::: field hideHomeContent
@type boolean
@default &lt;code&gt;true&lt;/code&gt;
@optional&lt;/p&gt;
&lt;p&gt;加密时在首页卡片、归档与 RSS 中隐藏文章摘要与字数，防止泄漏。
:::&lt;/p&gt;
&lt;p&gt;::::&lt;/p&gt;
&lt;h3&gt;其他&lt;/h3&gt;
&lt;p&gt;:::: field-group&lt;/p&gt;
&lt;p&gt;::: field lang
@type string
@optional&lt;/p&gt;
&lt;p&gt;文章语言代码（如 &lt;code&gt;zh_CN&lt;/code&gt;、&lt;code&gt;en&lt;/code&gt;、&lt;code&gt;ja&lt;/code&gt;）。缺省取站点语言。
:::&lt;/p&gt;
&lt;p&gt;::::&lt;/p&gt;
&lt;h2&gt;最小可用示例&lt;/h2&gt;
&lt;p&gt;只填必填项也能正常发布：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;---
title: &quot;我的第一篇文章&quot;
published: 2026-08-27
---
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;注意事项&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;&lt;code&gt;pinned&lt;/code&gt; 置顶&lt;/strong&gt;：多篇置顶时，置顶文章之间仍按发布日期排序。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code&gt;draft&lt;/code&gt; 草稿&lt;/strong&gt;：适合未完成的随笔，推送后不会出现在线上。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;加密安全&lt;/strong&gt;：&lt;code&gt;password&lt;/code&gt; 是前端加密，防浏览不防破解；敏感内容勿依赖它。&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code&gt;image&lt;/code&gt; 路径&lt;/strong&gt;：优先用相对路径与文章同目录存放，可享受构建期图片优化。&lt;/li&gt;
&lt;/ol&gt;
</content:encoded></item><item><title>Markdown 文件包含</title><link>https://blog.0v0.uno/posts/markdown-guide/includes/</link><guid isPermaLink="true">https://blog.0v0.uno/posts/markdown-guide/includes/</guid><description>构建期引入本地 Markdown 文件或其安全切片。</description><pubDate>Fri, 06 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;Shirone 可以引入一个本地 Markdown 文件，或它的一个安全切片。&lt;/p&gt;
&lt;p&gt;下面这行就是从 &lt;code&gt;src/content/snippets/include-example.md&lt;/code&gt; 的 &lt;code&gt;#public-api&lt;/code&gt; 区域实时引入的：&lt;/p&gt;
&lt;p&gt;&amp;lt;!-- @include: src/content/snippets/include-example.md#public-api --&amp;gt;&lt;/p&gt;
&lt;p&gt;也支持整文件与行号范围形式：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;&amp;lt;!-- @include: src/content/snippets/include-example.md --&amp;gt;
&amp;lt;!-- @include: src/content/snippets/include-example.md{1-4} --&amp;gt;
&amp;lt;!-- @include: src/content/snippets/include-example.md{5-} --&amp;gt;
&amp;lt;!-- @include: src/content/snippets/include-example.md{-4} --&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;围栏代码块内的 include 注释保持字面量，不会被展开。&lt;/p&gt;
</content:encoded></item><item><title>Markdown 荧光高亮</title><link>https://blog.0v0.uno/posts/markdown-guide/marker-highlights/</link><guid isPermaLink="true">https://blog.0v0.uno/posts/markdown-guide/marker-highlights/</guid><description>用令牌驱动的标记语法高亮正文中的关键短语。</description><pubDate>Fri, 06 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;荧光高亮把注意力引向某个特定短语，又不把周围段落变成独立组件。它在构建期渲染为原生 &lt;code&gt;&amp;lt;mark&amp;gt;&lt;/code&gt; 元素，并继承当前 M3E 色彩体系。&lt;/p&gt;
&lt;h2&gt;默认强调&lt;/h2&gt;
&lt;p&gt;用 &lt;code&gt;==text==&lt;/code&gt; 让文章主色承担强调作用。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;写法&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;适合标记 ==一个希望读者记住的关键结论==，同时段落其余部分照常延续。

短语需要更强层级时，标记内还可嵌套 ==嵌套的 **Markdown 强调**==。
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;渲染效果&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;适合标记 ==一个希望读者记住的关键结论==，同时段落其余部分照常延续。&lt;/p&gt;
&lt;p&gt;短语需要更强层级时，标记内还可嵌套 ==嵌套的 &lt;strong&gt;Markdown 强调&lt;/strong&gt;==。&lt;/p&gt;
&lt;h2&gt;语义色彩&lt;/h2&gt;
&lt;p&gt;需要不同的色调角色时，在结尾加 &lt;code&gt;{.变体}&lt;/code&gt; 后缀。可用变体：&lt;code&gt;primary&lt;/code&gt;、&lt;code&gt;secondary&lt;/code&gt;、&lt;code&gt;tertiary&lt;/code&gt;、&lt;code&gt;error&lt;/code&gt;、&lt;code&gt;tip&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;写法&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;- ==Primary 把短语关联到当前主题=={.primary}
- ==Secondary 让次要的区分保持低调=={.secondary}
- ==Tertiary 增加一个独立的编辑性信号=={.tertiary}
- ==Error 标出需要修正的条件=={.error}
- ==Tip 高亮实用建议=={.tip}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;渲染效果&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;==Primary 把短语关联到当前主题=={.primary}&lt;/li&gt;
&lt;li&gt;==Secondary 让次要的区分保持低调=={.secondary}&lt;/li&gt;
&lt;li&gt;==Tertiary 增加一个独立的编辑性信号=={.tertiary}&lt;/li&gt;
&lt;li&gt;==Error 标出需要修正的条件=={.error}&lt;/li&gt;
&lt;li&gt;==Tip 高亮实用建议=={.tip}&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;注意&lt;/h2&gt;
&lt;p&gt;像 &lt;code&gt;==literal marker syntax==&lt;/code&gt; 这样的行内代码与围栏示例保持字面量，因此文档可以放心讲解语法而不会触发它。&lt;/p&gt;
</content:encoded></item><item><title>MDX 集成与 M3E 原子组件</title><link>https://blog.0v0.uno/posts/markdown-guide/mdx-showcase/</link><guid isPermaLink="true">https://blog.0v0.uno/posts/markdown-guide/mdx-showcase/</guid><description>在 Shirone 中用 MDX、Svelte 5 交互孤岛与 Material 3 Expressive 设计令牌组合出富交互文章的完整指南。</description><pubDate>Fri, 06 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;:::tip
&lt;strong&gt;MDX（Markdown + JSX）&lt;/strong&gt; 弥合了静态写作与应用界面之间的鸿沟。在 Shirone 中，作者可以在文章内容里直接混用动态逻辑、响应式 Svelte 5 组件与 Material 3 设计令牌。
:::&lt;/p&gt;
&lt;h2&gt;1. Markdown 与 MDX 能力对照&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;能力&lt;/th&gt;
&lt;th&gt;标准 Markdown（&lt;code&gt;.md&lt;/code&gt;）&lt;/th&gt;
&lt;th&gt;Shirone MDX（&lt;code&gt;.mdx&lt;/code&gt;）&lt;/th&gt;
&lt;th&gt;执行方式&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;排版与结构&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;完整支持&lt;/td&gt;
&lt;td&gt;完整支持&lt;/td&gt;
&lt;td&gt;静态 SSR&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;代码高亮&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;行号、框架、可折叠&lt;/td&gt;
&lt;td&gt;行号、框架、可折叠&lt;/td&gt;
&lt;td&gt;静态 SSR（Expressive Code）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;图表与数学&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Mermaid、KaTeX&lt;/td&gt;
&lt;td&gt;Mermaid、KaTeX&lt;/td&gt;
&lt;td&gt;客户端增强&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;提示容器&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Note、Tip、Important、Warning、Caution&lt;/td&gt;
&lt;td&gt;Note、Tip、Important、Warning、Caution&lt;/td&gt;
&lt;td&gt;静态 SSR&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;M3E 展示原子&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;不可用&lt;/td&gt;
&lt;td&gt;直接集成（``、&lt;code&gt;&amp;lt;Skeleton&amp;gt;&lt;/code&gt;）&lt;/td&gt;
&lt;td&gt;纯 SSR（零客户端 JS）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Svelte 5 响应式孤岛&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;不可用&lt;/td&gt;
&lt;td&gt;按需水合（&lt;code&gt;&amp;lt;Button&amp;gt;&lt;/code&gt;、&lt;code&gt;&amp;lt;Switch&amp;gt;&lt;/code&gt;）&lt;/td&gt;
&lt;td&gt;&lt;code&gt;client:visible&lt;/code&gt; 懒水合&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;反馈与加载原子&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;不可用&lt;/td&gt;
&lt;td&gt;形变动画（&lt;code&gt;&amp;lt;LoadingIndicator&amp;gt;&lt;/code&gt;）&lt;/td&gt;
&lt;td&gt;&lt;code&gt;client:visible&lt;/code&gt; 响应式&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;动态 JSX 表达式&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;不可用&lt;/td&gt;
&lt;td&gt;原生求值（&lt;code&gt;{authorInfo.ui}&lt;/code&gt;）&lt;/td&gt;
&lt;td&gt;编译期 / 客户端&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;hr /&gt;
&lt;h2&gt;2. 动态表达式与数据映射&lt;/h2&gt;
&lt;p&gt;MDX 允许在文件顶部用 &lt;code&gt;export const&lt;/code&gt; 声明作用域常量，可行内求值或跨模板映射：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;核心框架&lt;/strong&gt;：{authorInfo.framework}&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;UI 引擎&lt;/strong&gt;：{authorInfo.ui}&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;设计令牌&lt;/strong&gt;：{authorInfo.tokens}&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;架构模式&lt;/strong&gt;：{authorInfo.architecture}&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;数组与集合可动态渲染为网格布局：&lt;/p&gt;
&lt;p&gt;&amp;lt;div class=&quot;grid grid-cols-1 md:grid-cols-2 gap-4 my-6&quot;&amp;gt;
{showcaseItems.map((item, idx) =&amp;gt; (
&amp;lt;div key={item.name} class=&quot;p-4 rounded-xl border border-[var(--outline-variant)] bg-[var(--surface-container-low)]&quot;&amp;gt;
&amp;lt;div class=&quot;flex items-center gap-2 mb-1&quot;&amp;gt;
&amp;lt;span class=&quot;w-6 h-6 rounded-full bg-[var(--primary)] text-[var(--on-primary)] text-xs flex items-center justify-center font-bold&quot;&amp;gt;
{idx + 1}
&amp;lt;/span&amp;gt;
&amp;lt;span class=&quot;font-bold text-[var(--on-surface)]&quot;&amp;gt;{item.name}&amp;lt;/span&amp;gt;
&amp;lt;/div&amp;gt;
&amp;lt;p class=&quot;text-sm text-[var(--on-surface-variant)] m-0&quot;&amp;gt;{item.desc}&amp;lt;/p&amp;gt;
&amp;lt;/div&amp;gt;
))}
&amp;lt;/div&amp;gt;&lt;/p&gt;
&lt;hr /&gt;
&lt;h2&gt;3. M3E 展示与布局基元（仅 SSR）&lt;/h2&gt;
&lt;p&gt;依据 Shirone 的组件架构（&lt;code&gt;docs/atomic-structure.md&lt;/code&gt;），无状态展示组件输出干净、无障碍的语义化 HTML，不带任何客户端运行时负载。&lt;/p&gt;
&lt;h3&gt;3.1 卡片容器（&lt;code&gt;Card.svelte&lt;/code&gt;）&lt;/h3&gt;
&lt;p&gt;&amp;lt;div class=&quot;grid grid-cols-1 md:grid-cols-3 gap-4 my-6&quot;&amp;gt;
&amp;lt;Card variant=&quot;filled&quot; class=&quot;!p-5&quot;&amp;gt;
&amp;lt;div class=&quot;font-bold text-[var(--primary)] mb-2&quot;&amp;gt;填充卡片&amp;lt;/div&amp;gt;
&amp;lt;div class=&quot;text-sm text-[var(--on-surface-variant)]&quot;&amp;gt;默认容器背景，无海拔阴影，适合成组的内容块。&amp;lt;/div&amp;gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;&amp;lt;div class=&quot;font-bold text-[var(--primary)] mb-2&quot;&amp;gt;海拔卡片&amp;lt;/div&amp;gt;
&amp;lt;div class=&quot;text-sm text-[var(--on-surface-variant)]&quot;&amp;gt;一级容器海拔，带交互态层叠，视觉更聚焦。&amp;lt;/div&amp;gt;



&amp;lt;div class=&quot;font-bold text-[var(--primary)] mb-2&quot;&amp;gt;描边卡片&amp;lt;/div&amp;gt;
&amp;lt;div class=&quot;text-sm text-[var(--on-surface-variant)]&quot;&amp;gt;清晰的 1px 描边，在中性表面上提供干净的分隔。&amp;lt;/div&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&amp;lt;/div&amp;gt;&lt;/p&gt;
&lt;h3&gt;3.2 强调条与徽标（&lt;code&gt;AccentBar&lt;/code&gt; 与 &lt;code&gt;Badge&lt;/code&gt;）&lt;/h3&gt;
&lt;p&gt;&amp;lt;div class=&quot;flex items-center gap-4 my-4 p-4 rounded-lg bg-[var(--surface-container-high)]&quot;&amp;gt;&lt;/p&gt;
&lt;p&gt;&amp;lt;div class=&quot;flex-1&quot;&amp;gt;
&amp;lt;span class=&quot;font-bold text-lg&quot;&amp;gt;系统公告&amp;lt;/span&amp;gt;
&amp;lt;p class=&quot;text-xs text-[var(--on-surface-variant)] m-0&quot;&amp;gt;把 AccentBar 与 Badge 组合，做出醒目的视觉提示&amp;lt;/p&amp;gt;
&amp;lt;/div&amp;gt;
M3E v0.192
&amp;lt;/div&amp;gt;&lt;/p&gt;
&lt;h3&gt;3.3 骨架屏占位（&lt;code&gt;Skeleton.svelte&lt;/code&gt;）&lt;/h3&gt;
&lt;p&gt;用于预览布局骨架或原型化异步状态：&lt;/p&gt;
&lt;p&gt;&amp;lt;div class=&quot;flex flex-col gap-3 my-6 p-5 rounded-xl border border-[var(--outline-variant)] bg-[var(--surface-container-low)]&quot;&amp;gt;
&amp;lt;div class=&quot;flex items-center gap-3&quot;&amp;gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;&amp;lt;div class=&quot;flex flex-col gap-1.5 flex-1&quot;&amp;gt;
  
  
&amp;lt;/div&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&amp;lt;/div&amp;gt;&lt;/p&gt;
&lt;p&gt;&amp;lt;/div&amp;gt;&lt;/p&gt;
&lt;hr /&gt;
&lt;h2&gt;4. 反馈与加载指示器&lt;/h2&gt;
&lt;p&gt;Shirone 具备完整的 Material 3 Expressive 动效与反馈原子：&lt;/p&gt;
&lt;h3&gt;4.1 形变加载指示器（&lt;code&gt;LoadingIndicator.svelte&lt;/code&gt;）&lt;/h3&gt;
&lt;p&gt;基于 &lt;code&gt;androidx.graphics.shapes&lt;/code&gt; 多边形形变，提供平滑弹簧插值的 7 形状动画：&lt;/p&gt;
&lt;p&gt;&amp;lt;div class=&quot;grid grid-cols-1 md:grid-cols-3 gap-4 my-6 p-6 rounded-2xl bg-[var(--surface-container)] border border-[var(--outline-variant)] text-center&quot;&amp;gt;
&amp;lt;div class=&quot;flex flex-col items-center gap-2&quot;&amp;gt;
&amp;lt;div class=&quot;h-16 flex items-center justify-center&quot;&amp;gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;&amp;lt;/div&amp;gt;
&amp;lt;span class=&quot;text-xs text-[var(--on-surface-variant)]&quot;&amp;gt;不确定形状形变&amp;lt;/span&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&amp;lt;/div&amp;gt;&lt;/p&gt;
&lt;p&gt;&amp;lt;div class=&quot;flex flex-col items-center gap-2&quot;&amp;gt;
&amp;lt;div class=&quot;h-16 flex items-center justify-center&quot;&amp;gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;&amp;lt;/div&amp;gt;
&amp;lt;span class=&quot;text-xs text-[var(--on-surface-variant)]&quot;&amp;gt;内含圆形变体&amp;lt;/span&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&amp;lt;/div&amp;gt;&lt;/p&gt;
&lt;p&gt;&amp;lt;div class=&quot;flex flex-col items-center gap-2&quot;&amp;gt;
&amp;lt;div class=&quot;h-16 flex items-center justify-center&quot;&amp;gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;&amp;lt;/div&amp;gt;
&amp;lt;span class=&quot;text-xs text-[var(--on-surface-variant)]&quot;&amp;gt;确定性进度（68%）&amp;lt;/span&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&amp;lt;/div&amp;gt;
&amp;lt;/div&amp;gt;&lt;/p&gt;
&lt;h3&gt;4.2 线性与不确定进度（&lt;code&gt;ProgressIndicator.svelte&lt;/code&gt;）&lt;/h3&gt;
&lt;p&gt;&amp;lt;div class=&quot;flex flex-col gap-4 my-6 p-6 rounded-2xl bg-[var(--surface-container)] border border-[var(--outline-variant)]&quot;&amp;gt;
&amp;lt;div class=&quot;flex flex-col gap-2&quot;&amp;gt;
&amp;lt;div class=&quot;flex justify-between text-xs text-[var(--on-surface-variant)]&quot;&amp;gt;
&amp;lt;span&amp;gt;管线编译&amp;lt;/span&amp;gt;
&amp;lt;span&amp;gt;80%&amp;lt;/span&amp;gt;
&amp;lt;/div&amp;gt;&lt;/p&gt;
&lt;p&gt;&amp;lt;/div&amp;gt;&lt;/p&gt;
&lt;p&gt;&amp;lt;div class=&quot;flex flex-col gap-2 mt-2&quot;&amp;gt;
&amp;lt;div class=&quot;text-xs text-[var(--on-surface-variant)]&quot;&amp;gt;连续双线动画&amp;lt;/div&amp;gt;&lt;/p&gt;
&lt;p&gt;&amp;lt;/div&amp;gt;
&amp;lt;/div&amp;gt;&lt;/p&gt;
&lt;hr /&gt;
&lt;h2&gt;5. 交互式 Svelte 5 孤岛&lt;/h2&gt;
&lt;p&gt;用 &lt;code&gt;client:visible&lt;/code&gt; 声明的组件，会在进入视口时经 &lt;code&gt;IntersectionObserver&lt;/code&gt; 懒水合：&lt;/p&gt;
&lt;h3&gt;5.1 按钮矩阵（&lt;code&gt;Button.svelte&lt;/code&gt;）&lt;/h3&gt;
&lt;p&gt;&amp;lt;div class=&quot;flex flex-wrap items-center gap-3 my-6 p-4 rounded-xl border border-[var(--outline-variant)]&quot;&amp;gt;
填充按钮
海拔
色调按钮
描边
文本按钮
&amp;lt;/div&amp;gt;&lt;/p&gt;
&lt;h3&gt;5.2 筛选芯片与分段按钮（&lt;code&gt;Chips&lt;/code&gt; 与 &lt;code&gt;SegmentedButton&lt;/code&gt;）&lt;/h3&gt;
&lt;p&gt;&amp;lt;div class=&quot;flex flex-col gap-4 my-6 p-6 rounded-2xl bg-[var(--surface-container)] border border-[var(--outline-variant)]&quot;&amp;gt;
&amp;lt;div&amp;gt;
&amp;lt;div class=&quot;text-xs font-bold text-[var(--on-surface-variant)] mb-2&quot;&amp;gt;M3E 筛选芯片&amp;lt;/div&amp;gt;&lt;/p&gt;
&lt;p&gt;&amp;lt;/div&amp;gt;&lt;/p&gt;
&lt;p&gt;&amp;lt;div&amp;gt;
&amp;lt;div class=&quot;text-xs font-bold text-[var(--on-surface-variant)] mb-2&quot;&amp;gt;分段控件&amp;lt;/div&amp;gt;&lt;/p&gt;
&lt;p&gt;&amp;lt;/div&amp;gt;
&amp;lt;/div&amp;gt;&lt;/p&gt;
&lt;h3&gt;5.3 开关、复选框与滑块（&lt;code&gt;Switch&lt;/code&gt;、&lt;code&gt;Checkbox&lt;/code&gt;、&lt;code&gt;Slider&lt;/code&gt;）&lt;/h3&gt;
&lt;p&gt;&amp;lt;div class=&quot;flex flex-col gap-4 my-6 p-6 rounded-2xl bg-[var(--surface-container)] border border-[var(--outline-variant)]&quot;&amp;gt;
&amp;lt;div class=&quot;flex items-center justify-between&quot;&amp;gt;
&amp;lt;span class=&quot;font-bold text-sm&quot;&amp;gt;带状态图标的开关&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;&amp;lt;/div&amp;gt;&lt;/p&gt;
&lt;p&gt;&amp;lt;div class=&quot;flex items-center justify-between&quot;&amp;gt;
&amp;lt;span class=&quot;font-bold text-sm&quot;&amp;gt;选择复选框&amp;lt;/span&amp;gt;
&amp;lt;div class=&quot;flex items-center gap-4&quot;&amp;gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;&amp;lt;/div&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&amp;lt;/div&amp;gt;&lt;/p&gt;
&lt;p&gt;&amp;lt;div class=&quot;flex flex-col gap-2&quot;&amp;gt;
&amp;lt;span class=&quot;font-bold text-sm&quot;&amp;gt;色相光谱滑块&amp;lt;/span&amp;gt;&lt;/p&gt;
&lt;p&gt;&amp;lt;/div&amp;gt;
&amp;lt;/div&amp;gt;&lt;/p&gt;
&lt;h3&gt;5.4 输入控件（&lt;code&gt;TextField.svelte&lt;/code&gt;）&lt;/h3&gt;
&lt;p&gt;&amp;lt;div class=&quot;grid grid-cols-1 md:grid-cols-2 gap-4 my-6&quot;&amp;gt;&lt;/p&gt;
&lt;p&gt;&amp;lt;/div&amp;gt;&lt;/p&gt;
&lt;hr /&gt;
&lt;h2&gt;6. Markdown 扩展兼容性&lt;/h2&gt;
&lt;p&gt;Shirone 的 SSOT 统一插件管线对所有 Markdown 扩展保持完整兼容：&lt;/p&gt;
&lt;h3&gt;6.1 GitHub 仓库卡片&lt;/h3&gt;
&lt;p&gt;::github{repo=&quot;saicaca/fuwari&quot;}&lt;/p&gt;
&lt;h3&gt;6.2 Mermaid 架构图&lt;/h3&gt;
&lt;pre&gt;&lt;code&gt;flowchart TD
    MDX[MDX 源码入口] --&amp;gt; Compiler[&quot;@astrojs/mdx 编译器&quot;]
    Compiler --&amp;gt; Plugins[&quot;Remark / Rehype SSOT 管线&quot;]
    Plugins --&amp;gt; Islands[&quot;Svelte 5 交互孤岛&quot;]
    Islands --&amp;gt; Swup[&quot;Swup 客户端导航壳&quot;]
    Swup --&amp;gt; Screen[&quot;M3E Expressive 文章视图&quot;]
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;6.3 数学表达式（LaTeX / KaTeX）&lt;/h3&gt;
&lt;p&gt;行内公式：质能方程 $E = mc^2$ 与高斯积分 $\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}$。&lt;/p&gt;
&lt;p&gt;块级公式：&lt;/p&gt;
&lt;p&gt;$$
\mathcal{L}&lt;em&gt;{M3E} = \sum&lt;/em&gt;{i=1}^{N} \left( \text{Token}_i \cdot \text{ContrastRatio} \right) + \lambda |\text{MotionElegance}|
$$&lt;/p&gt;
&lt;hr /&gt;
&lt;h2&gt;7. 小结&lt;/h2&gt;
&lt;p&gt;MDX 的原生集成让技术写作者在保持 Shirone 超快静态性能的同时，构建出富交互文档。所有组件遵循 Material 3 Expressive 令牌设计体系，确保一致性、无障碍与视觉和谐。&lt;/p&gt;
</content:encoded></item><item><title>Mermaid 图表图集</title><link>https://blog.0v0.uno/posts/markdown-guide/mermaid/</link><guid isPermaLink="true">https://blog.0v0.uno/posts/markdown-guide/mermaid/</guid><description>流程、交互、数据模型、日程与项目历史等各类 Mermaid 图表示例。</description><pubDate>Fri, 06 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;Mermaid 把 Markdown 里的文本描述变成图表。下面用 Shirone 的内容工作流演示技术文章与项目笔记中常用的各类图。&lt;/p&gt;
&lt;h2&gt;流程图&lt;/h2&gt;
&lt;p&gt;流程图描述一个过程，包括判断与回到前面步骤的路径。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;flowchart TD
    accTitle: 文章发布流程
    accDescr: 一篇文章在发布前要经过撰写、校验、预览与构建；校验未通过则返回修改。
    Draft[撰写 Markdown] --&amp;gt; Check{校验通过?}
    Check --&amp;gt;|否| Revise[修改文章]
    Revise --&amp;gt; Check
    Check --&amp;gt;|是| Preview[本地预览]
    Preview --&amp;gt; Build[构建静态页]
    Build --&amp;gt; Publish[发布]
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;时序图&lt;/h2&gt;
&lt;p&gt;时序图按时间顺序呈现参与者之间的协作。下面跟踪一次 Swup 站内导航，从请求到 Mermaid 渲染。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sequenceDiagram
    accTitle: 站内导航后的图表渲染
    accDescr: 读者发起导航，Swup 替换文章内容，Mermaid 渲染器在新页面增强图表。
    actor Reader as 读者
    participant Browser as 浏览器
    participant Swup
    participant Content as 文章区域
    participant Renderer as Mermaid 渲染器
    Reader-&amp;gt;&amp;gt;Browser: 打开另一篇文章
    Browser-&amp;gt;&amp;gt;Swup: 发起站内导航
    Swup-&amp;gt;&amp;gt;Content: 替换页面内容
    Swup--&amp;gt;&amp;gt;Renderer: 触发 content:replace
    Renderer-&amp;gt;&amp;gt;Content: 查找 Mermaid 容器
    Renderer--&amp;gt;&amp;gt;Browser: 插入带主题的 SVG
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;实体关系图&lt;/h2&gt;
&lt;p&gt;实体关系图建模结构化数据，以及作者、文章、标签与评论之间的联系。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;erDiagram
    accTitle: 博客内容关系
    accDescr: 作者撰写文章，文章接收评论，关联记录把文章连接到多个标签。
    AUTHOR ||--o{ POST : writes
    POST ||--o{ COMMENT : receives
    POST ||--o{ POST_TAG : classified_by
    TAG ||--o{ POST_TAG : groups
    AUTHOR {
        string id PK
        string display_name
    }
    POST {
        string slug PK
        string title
        datetime published_at
        string author_id FK
    }
    COMMENT {
        string id PK
        string post_slug FK
        string body
    }
    TAG {
        string id PK
        string label
    }
    POST_TAG {
        string post_slug FK
        string tag_id FK
    }
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;类图&lt;/h2&gt;
&lt;p&gt;类图传达软件设计中的职责、公开方法与依赖方向。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;classDiagram
    accTitle: Markdown 渲染模块
    accDescr: 内容管线用 Mermaid 插件生成回退标记，客户端渲染器再把它增强为 SVG。
    class ContentPipeline {
        +render(markdown)
        +collectMetadata()
    }
    class MermaidPlugin {
        +transform(codeFence)
        +createFallback()
    }
    class DiagramRenderer {
        +initialize()
        +renderAll()
        +refreshTheme()
    }
    class ThemeTokens {
        +primary
        +surface
        +outline
    }
    ContentPipeline --&amp;gt; MermaidPlugin : uses
    DiagramRenderer --&amp;gt; MermaidPlugin : enhances output
    DiagramRenderer --&amp;gt; ThemeTokens : reads
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;状态图&lt;/h2&gt;
&lt;p&gt;状态图展示对象的生命周期，以及推动它在状态间迁移的事件。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;stateDiagram-v2
    accTitle: 文章生命周期
    accDescr: 文章从草稿到评审再到发布，可能返回修改，最终被归档。
    [*] --&amp;gt; Draft
    Draft --&amp;gt; InReview : 提交
    InReview --&amp;gt; Draft : 要求修改
    InReview --&amp;gt; Published : 通过
    Published --&amp;gt; Draft : 撤回
    Published --&amp;gt; Archived : 归档
    Archived --&amp;gt; [*]
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;XY 图&lt;/h2&gt;
&lt;p&gt;XY 图把柱状与折线组合，在同一坐标轴上对比数值与趋势。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;xychart-beta
    accTitle: 六周内容表现
    accDescr: 柱状表示归一化的周发布量，折线表示归一化的阅读完成率。
    title &quot;六周内容表现&quot;
    x-axis &quot;周&quot; [1, 2, 3, 4, 5, 6]
    y-axis &quot;相对得分&quot; 0 --&amp;gt; 100
    bar [36, 52, 44, 68, 76, 84]
    line [48, 55, 62, 61, 73, 81]
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;饼图&lt;/h2&gt;
&lt;p&gt;饼图紧凑地对比各类别对整体的贡献。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;pie showData
    accTitle: 文章主题占比
    accDescr: 工程类占四成，设计系统占两成半，其余由指南与随笔平分。
    title 文章主题占比
    &quot;工程&quot; : 40
    &quot;设计系统&quot; : 25
    &quot;指南&quot; : 20
    &quot;随笔&quot; : 15
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;甘特图&lt;/h2&gt;
&lt;p&gt;甘特图沿日历时间线安排任务、依赖与里程碑。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;gantt
    accTitle: 主题发布计划
    accDescr: 发布计划从需求与交互设计，推进到组件开发、测试与发布。
    title 主题发布计划
    dateFormat YYYY-MM-DD
    axisFormat %m/%d
    section 设计
    确认需求 :done, brief, 2024-05-06, 2d
    细化交互 :done, interaction, after brief, 3d
    section 实现
    开发组件 :active, components, after interaction, 6d
    编写示例 :examples, after interaction, 4d
    section 验证
    自动化测试 :tests, after components, 3d
    发布 :milestone, release, after tests, 0d
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;思维导图&lt;/h2&gt;
&lt;p&gt;思维导图把一个中心主题展开为相关领域与支撑概念。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;mindmap
  root((Shirone))
    内容体验
      Markdown
      搜索
      图表
    界面体系
      M3E 令牌
      响应式布局
      配色方案
    工程质量
      Astro Check
      Playwright
      无障碍
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;时间线&lt;/h2&gt;
&lt;p&gt;时间线在不需精确日历时长的情况下，概括重要事件或阶段。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;timeline
    title Mermaid 支持的演进
    管线设计 : 识别 Mermaid 围栏
             : 保留源码回退
    客户端增强 : 按需加载运行时
               : 应用主题令牌
    可靠性 : 支持 Swup 导航
           : 验证响应式与无障碍输出
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;用户旅程&lt;/h2&gt;
&lt;p&gt;用户旅程图把任务各阶段的动作、参与者与体验评分结合起来。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;journey
    accTitle: 读者理解一篇技术文章
    accDescr: 读者发现文章，结合正文与图表理解它，然后探索相关主题。
    title 读者理解一篇技术文章
    section 发现
      浏览文章列表: 4: 读者
      选择一个主题: 5: 读者
    section 理解
      阅读文章: 4: 读者
      查看关系图: 5: 读者
    section 继续
      打开相关文章: 4: 读者
      收藏页面: 3: 读者
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;Git 图&lt;/h2&gt;
&lt;p&gt;Git 图展示功能分支在合并回主干之前的工作进展。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;gitGraph
    accTitle: Mermaid 功能分支历史
    accDescr: 功能分支先添加渲染器与测试，再合并进主分支发布。
    commit id: &quot;base&quot;
    branch mermaid
    checkout mermaid
    commit id: &quot;add-renderer&quot;
    commit id: &quot;add-tests&quot;
    checkout main
    merge mermaid id: &quot;merge-mermaid&quot;
    commit id: &quot;release&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;看板&lt;/h2&gt;
&lt;p&gt;看板按工作流状态对任务分组，让当前进展一目了然。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;kanban
  backlog[待办]
    docs[编写作者文档]
    examples[扩充示例数据]
  active[进行中]
    themes[验证主题适配]
  complete[完成]
    fallback[源码回退]
    rendering[客户端渲染]
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;桑基图&lt;/h2&gt;
&lt;p&gt;桑基图用连线宽度展示流量或其他量在节点间的流动。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;sankey-beta
Landing,Reading,720
Discovery,Reading,430
Reading,Explore,360
Reading,Topics,210
Reading,Outbound,140
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;标签内换行&lt;/h2&gt;
&lt;p&gt;HTML 标签接受换行符，因此标签可以换行而不加宽图表。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;flowchart LR
  A[第一行&amp;lt;br&amp;gt;第二行] --&amp;gt; B[普通标签]
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;每个示例都用标准的 &lt;code&gt;mermaid&lt;/code&gt; 代码围栏。服务端保留可读的源码标记，浏览器再把它增强为跟随当前主题的 SVG。主题切换或 Swup 导航到本文时，图表会重新渲染。&lt;/p&gt;
</content:encoded></item><item><title>Markdown 选项组（Tabs）</title><link>https://blog.0v0.uno/posts/markdown-guide/option-groups/</link><guid isPermaLink="true">https://blog.0v0.uno/posts/markdown-guide/option-groups/</guid><description>把相关的 Markdown 备选方案呈现为紧凑、可同步的 M3E 选项组。</description><pubDate>Fri, 06 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;选项组把等价的操作说明聚在一起，无需重复外围的解释文字。每个选项接受完整块级 Markdown，选中值还能与同页另一组同步。&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;@tab 标题&lt;/code&gt; 划分一个标签页&lt;/li&gt;
&lt;li&gt;&lt;code&gt;@tab:active&lt;/code&gt; 标记默认激活项&lt;/li&gt;
&lt;li&gt;&lt;code&gt;@tab 标题#值&lt;/code&gt; 用 &lt;code&gt;#&lt;/code&gt; 后缀提供稳定的值（不改变可见标题）&lt;/li&gt;
&lt;li&gt;&lt;code&gt;::: tabs#同步id&lt;/code&gt; 让多组共享选择状态&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;基础用法（含默认激活）&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;写法&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;::: tabs#package-manager

@tab npm

用 npm 安装：

```powershell
npm install astro
```

@tab:active **pnpm**#pnpm

用 pnpm 安装：

```powershell
pnpm.cmd add astro
```

@tab Bun#bun

用 Bun 安装：

```powershell
bun add astro
```

:::
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;渲染效果&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;::: tabs#package-manager&lt;/p&gt;
&lt;p&gt;@tab npm&lt;/p&gt;
&lt;p&gt;用 npm 安装：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;npm install astro
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;@tab:active &lt;strong&gt;pnpm&lt;/strong&gt;#pnpm&lt;/p&gt;
&lt;p&gt;用 pnpm 安装：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;pnpm.cmd add astro
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;@tab Bun#bun&lt;/p&gt;
&lt;p&gt;用 Bun 安装：&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;bun add astro
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::&lt;/p&gt;
&lt;h2&gt;跨组同步&lt;/h2&gt;
&lt;p&gt;这组与上面共享 &lt;code&gt;package-manager&lt;/code&gt; id。在上面选择某一项，会联动更新下方匹配的命令，并为下次访问记住该选择。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;写法&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;::: tabs#package-manager

@tab npm

```powershell
npm run dev
```

@tab pnpm

```powershell
pnpm.cmd dev
```

@tab Bun#bun

```powershell
bun run dev
```

:::
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;渲染效果&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;::: tabs#package-manager&lt;/p&gt;
&lt;p&gt;@tab npm&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;npm run dev
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;@tab pnpm&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;pnpm.cmd dev
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;@tab Bun#bun&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;bun run dev
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::&lt;/p&gt;
&lt;h2&gt;较多备选&lt;/h2&gt;
&lt;p&gt;较长的选项行保持单行，窄屏下在自己的导航区内横向滚动。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;写法&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;::: tabs

@tab 本地工作站

开发功能时使用本地工具链。

@tab 托管预览环境

发布一个临时预览用于评审。

@tab 持续集成

对每次变更运行确定性校验。

@tab 生产部署

把验证过的产物发布到生产。

@tab 离线恢复流程

网络不可用时从本地产物恢复。

:::
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;渲染效果&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;::: tabs&lt;/p&gt;
&lt;p&gt;@tab 本地工作站&lt;/p&gt;
&lt;p&gt;开发功能时使用本地工具链。&lt;/p&gt;
&lt;p&gt;@tab 托管预览环境&lt;/p&gt;
&lt;p&gt;发布一个临时预览用于评审。&lt;/p&gt;
&lt;p&gt;@tab 持续集成&lt;/p&gt;
&lt;p&gt;对每次变更运行确定性校验。&lt;/p&gt;
&lt;p&gt;@tab 生产部署&lt;/p&gt;
&lt;p&gt;把验证过的产物发布到生产。&lt;/p&gt;
&lt;p&gt;@tab 离线恢复流程&lt;/p&gt;
&lt;p&gt;网络不可用时从本地产物恢复。&lt;/p&gt;
&lt;p&gt;:::&lt;/p&gt;
&lt;h2&gt;规则&lt;/h2&gt;
&lt;p&gt;每个组至少需要两个 &lt;code&gt;@tab&lt;/code&gt; 分节，且每个分节的正文需与标记之间空一行。非法或不完整的组保留为普通可读 Markdown。&lt;/p&gt;
</content:encoded></item><item><title>Markdown 剧透黑幕</title><link>https://blog.0v0.uno/posts/markdown-guide/spoilers/</link><guid isPermaLink="true">https://blog.0v0.uno/posts/markdown-guide/spoilers/</guid><description>隐藏行内答案，同时让剧透内容保持无障碍可访问。</description><pubDate>Fri, 06 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;剧透黑幕把简短答案或情节细节遮住，但不从文档中移除。悬浮、聚焦或激活该原生控件即可显现内容。&lt;/p&gt;
&lt;h2&gt;基础用法&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;写法&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;答案是 :spoiler[**42**]，这句话其余部分仍是普通 Markdown。
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;渲染效果&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;答案是 :spoiler[&lt;strong&gt;42&lt;/strong&gt;]，这句话其余部分仍是普通 Markdown。&lt;/p&gt;
&lt;h2&gt;含行内代码与较长内容&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;写法&lt;/strong&gt;&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;剧透内可包含 `行内代码`，也可以写 :spoiler[一段带**强调**的较长细节]。
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;渲染效果&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;剧透内可包含 &lt;code&gt;行内代码&lt;/code&gt;，也可以写 :spoiler[一段带&lt;strong&gt;强调&lt;/strong&gt;的较长细节]。&lt;/p&gt;
&lt;h2&gt;说明&lt;/h2&gt;
&lt;p&gt;生成的 HTML 使用带 &lt;code&gt;aria-expanded&lt;/code&gt; 状态的原生按钮。没有 JavaScript 时，悬浮和聚焦仍能显现文字；可选的运行时会额外提供点击与键盘切换。&lt;/p&gt;
</content:encoded></item><item><title>Markdown 步骤条</title><link>https://blog.0v0.uno/posts/markdown-guide/steps/</link><guid isPermaLink="true">https://blog.0v0.uno/posts/markdown-guide/steps/</guid><description>把有先后顺序的操作流程呈现为紧凑、无障碍的步骤流。</description><pubDate>Fri, 06 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;步骤条用于顺序很重要的操作流程。组件不打断文章阅读流：一条安静的序号导轨提供方向感，而标题、段落、链接、列表和代码仍保留各自的原生 Markdown 角色。&lt;/p&gt;
&lt;h2&gt;有序列表语法&lt;/h2&gt;
&lt;p&gt;把一个 Markdown 有序列表包进 &lt;code&gt;:::steps&lt;/code&gt; 容器，每个顶层列表项成为一步。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;:::steps[生产环境部署]
1. **克隆并准备工作区**

   克隆仓库并进入项目目录。

   ```powershell
   git clone https://github.com/LyraVoid/Shirone.git
   Set-Location Shirone
   ```

2. **安装依赖**

   使用仓库锁定的包管理器。

   ```powershell
   pnpm.cmd install
   ```

3. **运行项目检查**

   确认 Astro 诊断与 TypeScript 检查通过。

   ```powershell
   npx.cmd astro check
   pnpm.cmd type-check
   ```

4. **构建生产站点**

   生成静态站点与搜索索引。

   ```powershell
   pnpm.cmd build
   ```
:::
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;:::steps[生产环境部署]&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;克隆并准备工作区&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;克隆仓库并进入项目目录。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;git clone https://github.com/LyraVoid/Shirone.git
Set-Location Shirone
&lt;/code&gt;&lt;/pre&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;安装依赖&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;使用仓库锁定的包管理器。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;pnpm.cmd install
&lt;/code&gt;&lt;/pre&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;运行项目检查&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;确认 Astro 诊断与 TypeScript 检查通过。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;npx.cmd astro check
pnpm.cmd type-check
&lt;/code&gt;&lt;/pre&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;构建生产站点&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;生成静态站点与搜索索引。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;pnpm.cmd build
&lt;/code&gt;&lt;/pre&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;:::&lt;/p&gt;
&lt;h2&gt;选项&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;:::steps[标题]&lt;/code&gt; 或 &lt;code&gt;title=&quot;标题&quot;&lt;/code&gt; 添加可见标签与无障碍名称。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;start=4&lt;/code&gt; 修改首个显示步骤的序号。&lt;/li&gt;
&lt;li&gt;容器内必须恰好只有一个有序列表。非法或混合输入保留为普通可读 Markdown，不做启发式解释。&lt;/li&gt;
&lt;li&gt;渲染在站点构建期完成，不增加客户端 JavaScript 或网络请求。&lt;/li&gt;
&lt;/ul&gt;
</content:encoded></item><item><title>在文章中嵌入视频</title><link>https://blog.0v0.uno/posts/markdown-guide/video/</link><guid isPermaLink="true">https://blog.0v0.uno/posts/markdown-guide/video/</guid><description>演示如何在博客文章中嵌入各平台视频。</description><pubDate>Fri, 06 Nov 2026 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;除了直接粘贴平台 iframe 嵌入代码，Shirone 还提供各平台的专用指令，均为 SSR facade：初始只渲染封面占位，接近视口或点击时才加载真实播放器。&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;---
title: 在文章中嵌入视频
published: 2023-10-19
---
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;YouTube&lt;/h2&gt;
&lt;p&gt;::youtube{id=&quot;5gIf0_xpFPI&quot; title=&quot;YouTube 视频&quot; preload=&quot;auto&quot;}&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;::youtube{id=&quot;5gIf0_xpFPI&quot; title=&quot;YouTube 视频&quot; preload=&quot;auto&quot;}
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;Bilibili&lt;/h2&gt;
&lt;p&gt;::bilibili{bvid=&quot;BV1fK4y1s7Qf&quot; title=&quot;Bilibili 视频&quot; p=1 preload=&quot;auto&quot;}&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;::bilibili{bvid=&quot;BV1fK4y1s7Qf&quot; title=&quot;Bilibili 视频&quot; p=1 preload=&quot;auto&quot;}
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;AcFun&lt;/h2&gt;
&lt;p&gt;::acfun{acid=&quot;ac48649632&quot; title=&quot;AcFun 视频&quot; preload=&quot;auto&quot;}&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;::acfun{acid=&quot;ac48649632&quot; title=&quot;AcFun 视频&quot; preload=&quot;auto&quot;}
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;ArtPlayer（自建/直链）&lt;/h2&gt;
&lt;p&gt;::artplayer{src=&quot;https://www.pexels.com/download/video/38538991/&quot; title=&quot;Sintel 预告片&quot; preload=&quot;auto&quot;}&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;::artplayer{src=&quot;https://www.pexels.com/download/video/38538991/&quot; title=&quot;Sintel 预告片&quot; preload=&quot;auto&quot;}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;preload=&quot;auto&quot;&lt;/code&gt; 会在视频接近视口时预加载播放器；默认 &lt;code&gt;none&lt;/code&gt; 则需点击才加载。&lt;/p&gt;
</content:encoded></item></channel></rss>