<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xml:lang="zh_CN">
  <title>QAQ</title>
  <subtitle>欢迎来到世界</subtitle>
  <link href="https://blog.0v0.uno/" rel="alternate" type="text/html"/>
  <link href="https://blog.0v0.uno/atom.xml" rel="self" type="application/atom+xml"/>
  <id>https://blog.0v0.uno/</id>
  <updated>2026-11-19T12:48:11.000Z</updated>
  <entry>
    <title>不同网络下的 OneBot WebSocket 通信</title>
    <link href="https://blog.0v0.uno/posts/deploy/astrbot-adapter-different-network/" rel="alternate" type="text/html"/>
    <id>https://blog.0v0.uno/posts/deploy/astrbot-adapter-different-network/</id>
    <published>2026-11-15T07:48:24.000Z</published>
    <updated>2026-11-19T12:48:11.000Z</updated>
    <summary>NapCat/SnowLuma 和 AstrBot 不在同一 Docker 网络时，通过宿主机 6199 端口和 host.docker.internal 建立 OneBot WebSocket 连接。</summary>
    <content type="html"><![CDATA[<p>NapCat/SnowLuma 和 AstrBot 不在同一个 Docker 网络时，容器名 <code>astrbot</code> 解析不到，需要让 AstrBot 把 <code>6199</code> 暴露到宿主机，客户端再通过宿主机地址连接。</p>
<p>适用场景：</p>
<ul>
<li>Windows 上的 NapCat 连接远程 Linux 服务器上的 AstrBot</li>
<li>NapCat/SnowLuma 在 <code>1panel-network</code>，AstrBot 在 <code>astrbot_astrbot-network</code></li>
<li>两个容器分属不同的 Compose 项目</li>
</ul>
<h1>1. AstrBot 暴露 6199</h1>
<p><code>6199</code> 是 ==AstrBot=={.primary} 的反向 WebSocket 端口，不是 NapCat/SnowLuma 的端口。</p>
<p>如果 AstrBot 是 1Panel 容器，在容器端口设置里加 <code>6199</code>：</p>
<p><img src="/images/posts/deploy/Astrbot/adapter/napcat/astrbot-port-6199.png" alt="AstrBot 暴露 6199 端口 w-100%" title="AstrBot 的 6185 和 6199 都映射到宿主机，网络是 astrbot_astrbot-network" /></p>
<p>如果是 Compose，在 <code>astrbot</code> 服务的 <code>ports</code> 下加：</p>
<pre><code>ports:
  - "6185:6185"
  - "6199:6199"
</code></pre>
<p>改完后重启 AstrBot。</p>
<p>:::caution[6199 不要对公网开放]
云安全组和 1Panel 防火墙只放行客户端的出口 IP。不要把 <code>6199</code> 开放给全部 IPv4 地址，否则任何人都能尝试连接 AstrBot 的反向 WebSocket。
:::</p>
<h1>2. 配置 NapCat</h1>
<p>判断是不是「同一网络」，看的是 ==Docker 网络名和它的子网=={.primary}，不是只看 IP。先上下对比 1Panel 里两个容器的网络设置：</p>
<p><strong>AstrBot 容器：</strong></p>
<p><img src="/images/posts/deploy/Astrbot/adapter/napcat/astrbot-port-6199.png" alt="AstrBot 容器使用 astrbot_astrbot-network w-100%" title="AstrBot 的 6185 和 6199 都映射到宿主机，网络是 astrbot_astrbot-network" /></p>
<p><strong>NapCat 容器：</strong></p>
<p><img src="/images/posts/deploy/Astrbot/adapter/napcat/container-ports.png" alt="NapCat 容器使用 1panel-network w-100%" title="端口 3000-3001、6099，网络 1panel-network" /></p>
<p>一个是 <code>astrbot_astrbot-network</code>（172.19.0.0/16），一个是 <code>1panel-network</code>（172.18.0.0/16）。网络名不同，子网也不同。</p>
<p>IP 结果只是辅助，真正的依据还是上面的网络名：</p>
<p>:::grid{columns=2}</p>
<p><img src="/images/posts/deploy/Astrbot/adapter/napcat/ip-same-network.png" alt="同一网络：AstrBot 和 NapCat 都在 astrbot_astrbot-network（172.19.0.0/16）" title="同一网络：都在 astrbot_astrbot-network，AstrBot 172.19.0.2，NapCat 172.19.0.3" /></p>
<p><img src="/images/posts/deploy/Astrbot/adapter/napcat/ip-cross-network.png" alt="不同网络：AstrBot 在 astrbot_astrbot-network（172.19.0.0/16），NapCat 在 1panel-network（172.18.0.0/16）" title="不同网络：AstrBot 172.19.0.2，NapCat 172.18.0.2；网络名不同，子网也不同" /></p>
<p>:::</p>
<table>
<thead>
<tr>
<th>对比项</th>
<th>同一网络</th>
<th>不同网络</th>
</tr>
</thead>
<tbody>
<tr>
<td>AstrBot 网络</td>
<td><code>astrbot_astrbot-network</code>（172.19.0.0/16）</td>
<td><code>astrbot_astrbot-network</code>（172.19.0.0/16）</td>
</tr>
<tr>
<td>NapCat 网络</td>
<td>同一个 <code>astrbot_astrbot-network</code></td>
<td><code>1panel-network</code>（172.18.0.0/16）</td>
</tr>
<tr>
<td>能否用 <code>astrbot</code></td>
<td>可以</td>
<td>不行，要走宿主机地址</td>
</tr>
</tbody>
</table>
<p>确认不在同一个 Docker 网络后，再给 NapCat 加主机映射。Docker 容器里的 <code>host.docker.internal</code> 默认不一定可用。Compose 写法：</p>
<pre><code>services:
  napcat:
    extra_hosts:
      - "host.docker.internal:host-gateway"
</code></pre>
<p>1Panel 里则在 NapCat 容器的「主机映射」中添加：</p>
<table>
<thead>
<tr>
<th>主机名</th>
<th>IP</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>host.docker.internal</code></td>
<td><code>host-gateway</code></td>
</tr>
</tbody>
</table>
<p><img src="/images/posts/deploy/Astrbot/adapter/napcat/host-gateway.png" alt="NapCat 添加 host.docker.internal 映射 w-100%" title="主机名 host.docker.internal，值 host-gateway" /></p>
<p>不同网络时，两个容器不在同一个 Docker 网络（子网也不同，见上方对比）。</p>
<p>如果 NapCat 必须留在 <code>1panel-network</code>（1Panel 自带、已有自己子网的网络），在 1Panel 里这样选：</p>
<p><img src="/images/posts/deploy/Astrbot/adapter/napcat/container-network.png" alt="NapCat 使用 1panel-network w-100%" title="NapCat 的网络选择 1panel-network" /></p>
<p>Windows 上的 NapCat 不需要 Docker 主机映射，确认能访问 AstrBot 的 <code>6199</code> 即可。</p>
<h1>3. Docker Compose 配置</h1>
<p>下面四份配置都用于不同网络：客户端单独一个网络，通过 <code>host.docker.internal</code> 访问宿主机上的 AstrBot <code>6199</code>。</p>
<h2>3.1 NapCat 单独部署（napcat-network）</h2>
<p>AstrBot 已经部署好，只新增 NapCat：</p>
<pre><code>services:
  napcat:
    image: mlikiowa/napcat-docker:latest
    container_name: napcat
    restart: always
    environment:
      - NAPCAT_UID=0
      - NAPCAT_GID=0
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
    ports:
      - "3000:3000"
      - "3001:3001"
      - "6099:6099"
    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
</code></pre>
<h2>3.2 NapCat + AstrBot 一起部署（分开网络）</h2>
<p>一份 Compose 里放两个服务，但网络分开。相比同一网络版本，多了 AstrBot 的 <code>6199</code> 映射和 NapCat 的 <code>extra_hosts</code>：</p>
<pre><code>services:
  astrbot:
    image: soulter/astrbot:latest
    container_name: astrbot
    restart: always
    security_opt:
      - no-new-privileges:true
    ports:
      - "6185:6185"
+      - "6199:6199"
    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:
+      - "host.docker.internal:host-gateway"
    ports:
      - "3000:3000"
      - "3001:3001"
      - "6099:6099"
    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
</code></pre>
<h2>3.3 SnowLuma 单独部署（snowluma-network）</h2>
<p>AstrBot 已经部署好，只新增 SnowLuma：</p>
<pre><code>services:
  snowluma:
    image: ${SNOWLUMA_IMAGE:-motricseven7/snowluma:latest}
    container_name: ${SNOWLUMA_CONTAINER:-snowluma}
    restart: unless-stopped
    user: "0:0"
    shm_size: 1gb
    cap_add:
      - SYS_PTRACE
    security_opt:
      - seccomp=unconfined
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
    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: "${SNOWLUMA_EXTRA_QQ_HOMES:-}"
      SNOWLUMA_QQ_FLAGS: "${SNOWLUMA_QQ_FLAGS:---disable-gpu --disable-software-rasterizer --disable-gpu-compositing}"
    ports:
      - "${VNC_PORT:-5900}:5900"
      - "${NOVNC_PORT:-6081}:6081"
      - "${SNOWLUMA_WEBUI_HOST_PORT:-5099}:${SNOWLUMA_WEBUI_PORT:-5099}"
      - "${ONEBOT_HTTP_PORT:-3000}:3000"
      - "${ONEBOT_WS_PORT:-3001}:3001"
    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
</code></pre>
<h2>3.4 SnowLuma + AstrBot 一起部署（分开网络）</h2>
<p>一份 Compose 里放两个服务，网络分开。相比同一网络版本，多了 AstrBot 的 <code>6199</code> 映射和 SnowLuma 的 <code>extra_hosts</code>：</p>
<pre><code>services:
  astrbot:
    image: soulter/astrbot:latest
    container_name: astrbot
    restart: always
    security_opt:
      - no-new-privileges:true
    ports:
      - "6185:6185"
+      - "6199:6199"
    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: "0:0"
    shm_size: 1gb
    cap_add:
      - SYS_PTRACE
    security_opt:
      - seccomp=unconfined
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
    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: "${SNOWLUMA_EXTRA_QQ_HOMES:-}"
      SNOWLUMA_QQ_FLAGS: "${SNOWLUMA_QQ_FLAGS:---disable-gpu --disable-software-rasterizer --disable-gpu-compositing}"
    ports:
      - "${VNC_PORT:-5900}:5900"
      - "${NOVNC_PORT:-6081}:6081"
      - "${SNOWLUMA_WEBUI_HOST_PORT:-5099}:${SNOWLUMA_WEBUI_PORT:-5099}"
      - "${ONEBOT_HTTP_PORT:-3000}:3000"
      - "${ONEBOT_WS_PORT:-3001}:3001"
    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
</code></pre>
<h1>4. 填写 WebSocket URL</h1>
<p>NapCat 在「网络配置 → 新建 → Websocket客户端」里填：</p>
<pre><code>ws://host.docker.internal:6199/ws
</code></pre>
<p><img src="/images/posts/deploy/Astrbot/adapter/napcat/ws-cross-network.png" alt="跨网络下填写 ws://host.docker.internal:6199/ws w-100%" title="名称 astrbot，URL ws://host.docker.internal:6199/ws，Token 留空" /></p>
<p>Windows 上的 NapCat 没有 Docker 网络，直接填服务器地址：</p>
<pre><code>ws://&lt;服务器IP&gt;:6199/ws
</code></pre>
<p>如果 AstrBot 在本机 Docker Desktop，则填 <code>ws://127.0.0.1:6199/ws</code>。</p>
<h1>5. 验证</h1>
<p>客户端日志出现反向 WebSocket 已启动，AstrBot 日志出现：</p>
<pre><code>aiocqhttp(OneBot v11) 适配器已连接。
</code></pre>
<p>就说明跨网络连接成功。NapCat/SnowLuma 的完整验证步骤见：</p>
<ul>
<li><a href="/posts/deploy/astrbot-adapter-napcat/">NapCat 接入</a></li>
<li><a href="/posts/deploy/astrbot-adapter-snowluma/">SnowLuma 接入</a></li>
</ul>
<h1>常见问题</h1>
<p>::: collapse</p>
<ul>
<li>
<p>客户端一直连接失败</p>
<p>确认 AstrBot 的 <code>6199</code> 已映射到宿主机，并且防火墙/安全组放行的来源包含客户端 IP。</p>
</li>
<li>
<p>Docker 客户端提示 <code>host.docker.internal</code> 解析失败</p>
<p>给客户端容器加 <code>extra_hosts: host.docker.internal:host-gateway</code>，或者在 1Panel 的主机映射里添加同样的记录。</p>
</li>
<li>
<p>Windows 上 NapCat 连不上</p>
<p>先用 <code>telnet &lt;服务器IP&gt; 6199</code> 或 <code>Test-NetConnection &lt;服务器IP&gt; -Port 6199</code> 确认端口可达。</p>
</li>
<li>
<p>6199 要不要开放到公网</p>
<p>不要。只放行客户端所在 IP；同网络部署不需要映射。</p>
</li>
</ul>
<p>:::</p>
]]></content>
    <author><name>卟瓿钚</name></author>
    <category term="私有化部署"/>
  </entry>
  <entry>
    <title>AstrBot 接入 QQ：NapCat（OneBot v11）</title>
    <link href="https://blog.0v0.uno/posts/deploy/astrbot-adapter-napcat/" rel="alternate" type="text/html"/>
    <id>https://blog.0v0.uno/posts/deploy/astrbot-adapter-napcat/</id>
    <published>2026-11-15T07:43:11.000Z</published>
    <updated>2026-11-19T12:48:11.000Z</updated>
    <summary>NapCat 通过 OneBot v11 接入 AstrBot：Windows / Linux Docker 部署、网络选择和 WebSocket 配置。</summary>
    <content type="html"><![CDATA[<p>NapCat 通过 <strong>OneBot v11</strong> 接入 AstrBot。顺序是先在 AstrBot 里创建适配器，再部署 NapCat，最后在 NapCat 里填 WebSocket 地址。</p>
<p>:::info[和 SnowLuma 二选一]
NapCat 和 <a href="/posts/deploy/astrbot-adapter-snowluma/">SnowLuma</a> 共用同一个 OneBot v11 适配器，选一个接入即可；两个客户端同时连同一个 <code>6199</code> 会冲突。
:::</p>
<h1>1. 在 AstrBot 中创建 OneBot v11 适配器</h1>
<p>打开 AstrBot WebUI，进入「机器人 → 创建机器人」：</p>
<p>:::steps[创建适配器]</p>
<ol>
<li>
<p><strong>创建机器人</strong></p>
<p>消息平台类别选 <code>OneBot v11</code>，机器人名称填 <code>qq</code>。</p>
</li>
<li>
<p><strong>填写反向 WebSocket</strong></p>
<p>反向 WebSocket 主机填 <code>0.0.0.0</code>，端口填 <code>6199</code>，Token 留空。</p>
<p><img src="/images/posts/deploy/Astrbot/adapter/napcat/astrbot-create-onebot.png" alt="AstrBot 创建 OneBot v11 机器人 w-100%" title="消息平台类别 OneBot v11，反向 WebSocket 主机 0.0.0.0，端口 6199" /></p>
</li>
<li>
<p><strong>保存并启用</strong></p>
<p>保存后回到机器人列表，确认 <code>qq</code> 处于运行中。NapCat 后面连的就是这个 <code>6199</code>。</p>
<p><img src="/images/posts/deploy/Astrbot/adapter/napcat/astrbot-bot-page.png" alt="AstrBot 机器人列表 w-100%" title="qq 使用 aiocqhttp，反向 WebSocket 端口 6199" />
:::</p>
</li>
</ol>
<h1>2. 部署 NapCat</h1>
<p>:::warning[NapCat 和 Desktop 都已删库]
NapCat 和 NapCatQQ-Desktop 的仓库都已被删除，下面的包名和下载入口仅作历史参考；找不到时使用你本地备份的安装包。
:::</p>
<p>:::info[端口]
AstrBot WebUI <code>6185</code>，NapCat WebUI <code>6099</code>。<code>6199</code> 只在跨网络时需要，同一网络不需要暴露；跨网络见 <a href="/posts/deploy/astrbot-adapter-different-network/">不同网络下的 OneBot WebSocket 通信</a>。
:::</p>
<h2>2.1 Windows 部署</h2>
<p>Windows 上不只有一个包，先按用途选：</p>
<table>
<thead>
<tr>
<th>包 / 工具</th>
<th>运行方式</th>
<th>需要预装</th>
<th>和日常 QQ 的关系</th>
<th>适合</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>NapCat.Framework</code></td>
<td>以插件/注入方式挂到已安装的 QQNT</td>
<td>QQNT</td>
<td>共用桌面 QQ 的登录态</td>
<td>已经有桌面 QQ，想直接复用</td>
</tr>
<tr>
<td><code>NapCat.Shell</code></td>
<td>独立无头进程</td>
<td>自己装 QQ + Node.js</td>
<td>独立</td>
<td>Linux/Docker、手动部署</td>
</tr>
<tr>
<td><code>NapCat.Shell.Windows.Node</code></td>
<td>自带 QQ + 便携 Node 的整合包</td>
<td>无</td>
<td>独立于日常 QQ</td>
<td>Windows 想解压即用</td>
</tr>
<tr>
<td><code>NapCat.Shell.Windows.OneKey</code></td>
<td>一键安装器，生成 <code>NapCat.XXXX.Shell</code></td>
<td>无，安装器会准备</td>
<td>取决于版本，可能和桌面 QQ 共用</td>
<td>Windows 想按向导安装</td>
</tr>
<tr>
<td>NapCatQQ Desktop</td>
<td>单 EXE 图形管理器</td>
<td>由工具引导安装</td>
<td>取决于底层 NapCat</td>
<td>Windows 桌面用户，推荐</td>
</tr>
</tbody>
</table>
<h3>方式一：Windows OneKey</h3>
<p>:::steps[Windows OneKey 启动]</p>
<ol>
<li>
<p><strong>下载并解压</strong></p>
<p>下载 <code>NapCat.Shell.Windows.OneKey.zip</code>，解压到普通目录，不要放 <code>Program Files</code> 或需要管理员权限的路径。</p>
</li>
<li>
<p><strong>运行安装器</strong></p>
<p>双击 <code>NapCatInstaller.exe</code>，等待它生成 <code>NapCat.XXXX.Shell</code> 文件夹。首次运行需要联网准备文件。</p>
</li>
<li>
<p><strong>启动 NapCat</strong></p>
<p>进入 <code>NapCat.XXXX.Shell</code>，双击 <code>napcat.bat</code>。控制台会打印 WebUI Token。</p>
</li>
<li>
<p><strong>登录 WebUI 和 QQ</strong></p>
<p>浏览器打开 <code>http://127.0.0.1:6099</code>，用日志里的 Token 登录，扫码登录 QQ。</p>
</li>
<li>
<p><strong>下一步</strong></p>
<p>Windows 上的 NapCat 和 AstrBot 通常不在同一 Docker 网络，WebSocket 地址见 <a href="/posts/deploy/astrbot-adapter-different-network/">不同网络下的 OneBot WebSocket 通信</a>。
:::</p>
</li>
</ol>
<p>:::tip[不想用安装器]
如果 OneKey 安装器下载失败，可以试 <code>NapCat.Shell.Windows.Node.zip</code>：自带 QQ 和便携 Node，解压后直接运行 <code>napcat.bat</code>，不依赖系统安装的 QQ/Node。
:::</p>
<h3>方式二：NapCatQQ Desktop（推荐）</h3>
<p>:::steps[NapCatQQ Desktop]</p>
<ol>
<li>
<p><strong>下载单文件工具</strong></p>
<p>下载 <code>NapCatQQ-Desktop</code> 的 EXE。它不依赖额外运行库，双击即可打开。</p>
</li>
<li>
<p><strong>按引导准备环境</strong></p>
<p>在工具里按引导安装或选择 QQ 与 NapCat；它会自动检测环境并给出安装入口。</p>
</li>
<li>
<p><strong>启动账号</strong></p>
<p>新建或选择账号，启动 NapCat，扫码登录 QQ。托盘可以后台托管，多账号在左侧切换。</p>
</li>
<li>
<p><strong>下一步</strong></p>
<p>Windows 上的 NapCat 和 AstrBot 通常不在同一 Docker 网络，WebSocket 地址见 <a href="/posts/deploy/astrbot-adapter-different-network/">不同网络下的 OneBot WebSocket 通信</a>。
:::</p>
</li>
</ol>
<p>:::tip[为什么推荐 Desktop]
单 EXE、图形界面、多账号、自动更新、托盘托管；比手动跑 <code>napcat.bat</code> 少踩路径和环境坑。
:::</p>
<h2>2.2 Linux Docker 部署</h2>
<h3>方式一：1Panel 容器部署</h3>
<p>:::steps[创建 NapCat 容器]</p>
<ol>
<li>
<p><strong>基本信息</strong></p>
<p>1Panel 里进入「容器 → 创建容器」，镜像填 <code>mlikiowa/napcat-docker:latest</code>，名称填 <code>napcat</code>，重启策略选 <code>always</code>。</p>
</li>
<li>
<p><strong>端口</strong></p>
<p>映射 <code>6099</code> 给 NapCat WebUI。<code>3000/3001</code> 是 OneBot HTTP/WS 服务，用反向 WS 接入 AstrBot 时可以不映射。</p>
</li>
<li>
<p><strong>环境变量</strong></p>
<pre><code>NAPCAT_UID=0
NAPCAT_GID=0
</code></pre>
<p>如果服务器用非 root 用户运行 Docker，把 <code>0</code> 换成 <code>id -u</code> / <code>id -g</code> 的实际值。</p>
</li>
<li>
<p><strong>挂载</strong></p>
<ul>
<li><code>/opt/astrbot/napcat/config</code> → <code>/app/napcat/config</code>：NapCat 配置</li>
<li><code>/opt/astrbot/ntqq</code> → <code>/app/.config/QQ</code>：QQ 数据</li>
<li><code>astrbot-data</code> → <code>/AstrBot/data</code>：共享 AstrBot 数据，发文件时才能读到
:::</li>
</ul>
</li>
</ol>
<p>在 NapCat 容器的「网络」里选择 AstrBot 容器所在的网络，例如 <code>astrbot_astrbot-network</code>。同一网络不需要主机映射，也不用暴露 AstrBot 的 <code>6199</code>。</p>
<p><img src="/images/posts/deploy/Astrbot/adapter/napcat/ip-same-network.png" alt="同一网络下两个容器的 IP w-100%" title="AstrBot 172.19.0.2，NapCat 172.19.0.3，说明在同一网络" /></p>
<p>:::tip[不同网络？]
NapCat 和 AstrBot 不在同一 Docker 网络时，见 <a href="/posts/deploy/astrbot-adapter-different-network/">不同网络下的 OneBot WebSocket 通信</a>。
:::</p>
<p>:::warning[网络名不要凭感觉填]
如果你按前面的文章用 <code>docker network create astrbot-network</code> 创建过网络，AstrBot 却跑在 Compose 生成的 <code>astrbot_astrbot-network</code> 上，NapCat 选错网络就会解析不到 <code>astrbot</code>。以 AstrBot 容器「网络」页显示的网络名为准，不要只看 IP。
:::</p>
<h3>方式二：Docker Compose 部署</h3>
<p>:::steps[部署 NapCat]</p>
<ol>
<li>
<p><strong>保存 NapCat 配置</strong></p>
<p>同一网络不需要改 AstrBot 的 <code>ports</code>，<code>6199</code> 只在容器网络内部使用。</p>
<pre><code>services:
  napcat:
    image: mlikiowa/napcat-docker:latest
    container_name: napcat
    restart: always
    environment:
      - NAPCAT_UID=0
      - NAPCAT_GID=0
    ports:
      - "6099:6099"
    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
</code></pre>
<p>保存为 <code>/opt/astrbot/compose.napcat.yml</code>。</p>
</li>
<li>
<p><strong>启动</strong></p>
<pre><code>cd /opt/astrbot
docker compose -f compose.napcat.yml up -d
</code></pre>
</li>
</ol>
<p>:::</p>
<p>:::warning[网络名和卷名要对应]
<code>name</code> 必须和 AstrBot 容器「网络」页显示的一致，常见的是 <code>astrbot_astrbot-network</code>；手工创建过 <code>astrbot-network</code> 就改成它。<code>astrbot-data</code> 也必须是已存在的卷；如果 AstrBot 用的是 <code>./data</code>，把挂载改成 <code>./data:/AstrBot/data</code>，并删掉顶层 <code>volumes:</code>。
:::</p>
<h3>方式三：AstrBot + NapCat 一起部署</h3>
<p>如果还没有单独部署 AstrBot，可以直接用一份 Compose 把两者一起拉起。两个容器都在 <code>astrbot-network</code>，共享 <code>astrbot-data</code>，<code>6199</code> 不映射到宿主机。</p>
<p>:::steps[一起部署]</p>
<ol>
<li>
<p><strong>保存配置</strong></p>
<pre><code>services:
  astrbot:
    image: soulter/astrbot:latest
    container_name: astrbot
    restart: always
    security_opt:
      - no-new-privileges:true
    ports:
      - "6185:6185" # 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:
      - "3000:3000"
      - "3001:3001"
      - "6099:6099" # 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
</code></pre>
<p>保存为 <code>/opt/astrbot/compose.napcat.yml</code>。</p>
</li>
<li>
<p><strong>启动</strong></p>
<pre><code>cd /opt/astrbot
docker compose -f compose.napcat.yml up -d
</code></pre>
</li>
</ol>
<p>:::</p>
<p>:::caution[只适用于同一网络]
这份配置依赖 <code>astrbot-network</code> 内部解析。Windows 或跨网络部署见 <a href="/posts/deploy/astrbot-adapter-different-network/">不同网络下的 OneBot WebSocket 通信</a>。
:::</p>
<h1>3. 配置 NapCat WebSocket</h1>
<p>NapCat 启动并登录 QQ 后，在 NapCat WebUI 里新建 WebSocket 客户端。同一网络填：</p>
<pre><code>ws://astrbot:6199/ws
</code></pre>
<p>:::tip[Windows 或跨网络？]
见 <a href="/posts/deploy/astrbot-adapter-different-network/">不同网络下的 OneBot WebSocket 通信</a>。
:::</p>
<p>:::steps[添加 WebSocket 客户端]</p>
<ol>
<li>
<p><strong>新建客户端</strong></p>
<p>打开 NapCat WebUI，进入「网络配置 → 新建 → Websocket客户端」。</p>
<p><img src="/images/posts/deploy/Astrbot/adapter/napcat/ws-menu.png" alt="NapCat 新建 WebSocket 客户端 w-100%" title="在网络配置里新建 Websocket客户端" /></p>
</li>
<li>
<p><strong>填写名称和 URL</strong></p>
<p>名称填 <code>astrbot</code>，URL 填 <code>ws://astrbot:6199/ws</code>，Token 留空。</p>
</li>
<li>
<p><strong>保存并启用</strong></p>
<p>保存后确认客户端处于启用状态。
:::</p>
</li>
</ol>
<p>同一网络的填写示例：</p>
<p><img src="/images/posts/deploy/Astrbot/adapter/napcat/ws-same-network.png" alt="同一网络下填写 ws://astrbot:6199/ws w-100%" title="名称 astrbot，URL ws://astrbot:6199/ws，Token 留空" /></p>
<h1>4. 登录 NapCat</h1>
<p>:::steps[登录 NapCat]</p>
<ol>
<li>
<p><strong>获取 Token</strong></p>
<p>浏览器打开 <code>http://&lt;服务器IP&gt;:6099/webui</code>。登录用的 Token 在容器日志里：</p>
<pre><code>docker logs napcat 2&gt;&amp;1 | grep -i -E "webui|token"
</code></pre>
<p>也可以到挂载出来的 <code>./napcat/config/webui.json</code> 里找 <code>token</code> 字段。</p>
<p><img src="/images/posts/deploy/Astrbot/verify/napcat-webui-token.png" alt="1Panel 中 NapCat 日志里的 WebUi Token 和访问地址 w-100%" title="红框中是带 token 的 WebUI 地址，token 就是登录凭证" /></p>
<p>截图中的 Token 仅作示例，请以自己日志里的值为准。</p>
</li>
<li>
<p><strong>登录 WebUI</strong></p>
<p>把日志里的 Token 填进 WebUI：</p>
<p><img src="/images/posts/deploy/Astrbot/verify/napcat-webui-login.png" alt="NapCat Web Login 输入 Token w-100%" title="在 Token 输入框填入日志里的 WebUi Token" /></p>
</li>
<li>
<p><strong>扫码登录 QQ</strong></p>
<p>如果 QQ 还没登录，NapCat 会要求扫码：</p>
<p><img src="/images/posts/deploy/Astrbot/verify/napcat-qq-qr.png" alt="NapCat 扫码登录 QQ w-100%" title="用手机 QQ 扫描二维码完成登录" /></p>
<p>登录成功后进入 NapCat 面板：</p>
<p><img src="/images/posts/deploy/Astrbot/verify/napcat-dashboard.png" alt="NapCat 面板首页 w-100%" title="在基础信息里确认 NapCat 版本、QQ 版本和运行状态" />
:::</p>
</li>
</ol>
<h1>5. 验证连接</h1>
<p>:::steps[验证连接]</p>
<ol>
<li>
<p><strong>看 NapCat 日志</strong></p>
<p>日志里出现反向 WebSocket 已启动，说明客户端在尝试连接。</p>
<p><img src="/images/posts/deploy/Astrbot/adapter/napcat/ws-connected-log.png" alt="NapCat 日志中的反向 WebSocket 服务 w-100%" title="日志里能看到 WebSocket 反向服务已启动" /></p>
</li>
<li>
<p><strong>看 AstrBot 日志</strong></p>
<p>出现下面这行，说明连接成功：</p>
<pre><code>aiocqhttp(OneBot v11) 适配器已连接。
</code></pre>
<p><img src="/images/posts/deploy/Astrbot/verify/astrbot-adapter-connected.png" alt="AstrBot 日志显示适配器已连接 w-100%" title="看到 aiocqhttp(OneBot v11) 适配器已连接即可" /></p>
</li>
<li>
<p><strong>发一条测试消息</strong></p>
<p>在 QQ 里私聊机器人发一条消息，AstrBot 日志出现 <code>收到 ... 测试</code>，说明消息已经从 NapCat 送到 AstrBot：</p>
<p><img src="/images/posts/deploy/Astrbot/adapter/napcat/test-message-no-model.png" alt="AstrBot 日志显示收到测试消息 w-100%" title="日志里出现「收到 ... 测试」，说明消息发送成功" /></p>
<p>如果下面还提示 <code>未找到任何对话模型（提供商）</code>，只说明还没配置模型，不影响这次连接验证；配置好模型后再发消息就能收到回复。
:::</p>
</li>
</ol>
<h1>常见问题</h1>
<p>::: collapse</p>
<ul>
<li>
<p>NapCat 日志一直提示连接失败</p>
<p>检查两个容器是不是在同一个网络，URL 里的 <code>astrbot</code> 必须能解析成 AstrBot 容器。不在同一网络时见 <a href="/posts/deploy/astrbot-adapter-different-network/">不同网络下的 OneBot WebSocket 通信</a>。</p>
</li>
<li>
<p>AstrBot 和 NapCat 一起部署时出现 Network 错误</p>
<p>检查 compose 里的网络名是否和 AstrBot 实际使用的网络一致；同一份 compose 里的两个服务必须加入同一个网络。</p>
</li>
<li>
<p>AstrBot 提示 Token 不匹配</p>
<p>AstrBot 的反向 WebSocket Token 和 NapCat 的 WebSocket 客户端 Token 必须一致；不想校验就两边都留空。</p>
</li>
<li>
<p>NapCat 发文件时提示找不到文件</p>
<p>AstrBot 和 NapCat 没有共享 <code>astrbot-data</code>；两个容器都要把同一个卷挂到 <code>/AstrBot/data</code>。</p>
</li>
<li>
<p>6199 要不要开放到公网</p>
<p>不要。同一网络不需要映射；跨网络的做法见 <a href="/posts/deploy/astrbot-adapter-different-network/">不同网络下的 OneBot WebSocket 通信</a>，且只放行客户端 IP。</p>
</li>
</ul>
<p>:::</p>
]]></content>
    <author><name>卟瓿钚</name></author>
    <category term="私有化部署"/>
  </entry>
  <entry>
    <title>AstrBot 接入 QQ：SnowLuma（OneBot v11）</title>
    <link href="https://blog.0v0.uno/posts/deploy/astrbot-adapter-snowluma/" rel="alternate" type="text/html"/>
    <id>https://blog.0v0.uno/posts/deploy/astrbot-adapter-snowluma/</id>
    <published>2026-11-15T07:43:11.000Z</published>
    <updated>2026-11-19T12:48:11.000Z</updated>
    <summary>SnowLuma 通过 OneBot v11 接入 AstrBot：AstrBot 适配器创建、WebSocket 反向客户端配置和连接验证。</summary>
    <content type="html"><![CDATA[<p>SnowLuma 通过 <strong>OneBot v11</strong> 接入 AstrBot。AstrBot 侧和 <a href="/posts/deploy/astrbot-adapter-napcat/">NapCat</a> 共用同一个适配器；这篇从创建适配器开始写，单独看也能跑通。</p>
<p>:::info[和 NapCat 二选一]
SnowLuma 和 NapCat 共用同一个 OneBot v11 适配器，选一个接入即可；两个客户端同时连同一个 <code>6199</code> 会冲突。
:::</p>
<h1>1. 在 AstrBot 中创建 OneBot v11 适配器</h1>
<p>如果已经按 NapCat 那篇创建过适配器，直接跳到<a href="#2-%E9%83%A8%E7%BD%B2-snowluma">第 2 节</a>。否则打开 AstrBot WebUI，进入「机器人 → 创建机器人」：</p>
<p>:::steps[创建适配器]</p>
<ol>
<li>
<p><strong>创建机器人</strong></p>
<p>消息平台类别选 <code>OneBot v11</code>，机器人名称填 <code>qq</code>。</p>
</li>
<li>
<p><strong>填写反向 WebSocket</strong></p>
<p>反向 WebSocket 主机填 <code>0.0.0.0</code>，端口填 <code>6199</code>，Token 留空。</p>
<p><img src="/images/posts/deploy/Astrbot/adapter/napcat/astrbot-create-onebot.png" alt="AstrBot 创建 OneBot v11 机器人 w-100%" title="消息平台类别 OneBot v11，反向 WebSocket 主机 0.0.0.0，端口 6199" /></p>
</li>
<li>
<p><strong>保存并启用</strong></p>
<p>保存后回到机器人列表，确认 <code>qq</code> 处于运行中。SnowLuma 后面连的就是这个 <code>6199</code>。</p>
<p><img src="/images/posts/deploy/Astrbot/adapter/napcat/astrbot-bot-page.png" alt="AstrBot 机器人列表 w-100%" title="qq 使用 aiocqhttp，反向 WebSocket 端口 6199" />
:::</p>
</li>
</ol>
<h1>2. 部署 SnowLuma</h1>
<p>:::warning[SnowLuma 已删库]
SnowLuma 因法律问题已被删除仓库，下面的配置仅作历史参考。
:::</p>
<p>:::info[端口]
AstrBot WebUI <code>6185</code>；</p>
<p>SnowLuma WebUI <code>5099</code>；</p>
<p>noVNC <code>6081</code>；</p>
<p><code>5900</code> 只有直连 VNC 时才需要。</p>
<p><code>6199</code> 同网络不需要暴露；跨网络见 <a href="/posts/deploy/astrbot-adapter-different-network/">不同网络下的 OneBot WebSocket 通信</a>。
:::</p>
<p>以 SnowLuma 为例，1Panel 防火墙放行 <code>6185</code>、<code>5099</code>、<code>6081</code> 即可：</p>
<p><img src="/images/posts/deploy/Astrbot/1panel/1panel-firewall-snowluma.png" alt="1Panel 防火墙放行 AstrBot、SnowLuma 和 noVNC 端口 w-100%" title="放行 6185、6081、5099，协议 TCP，来源全部 IPv4 地址" /></p>
<h2>2.1 单独部署 SnowLuma</h2>
<p>AstrBot 已经部署好时，只新增 SnowLuma。它使用自己的 <code>snowluma-network</code>，通过 <code>host.docker.internal</code> 访问宿主机上的 AstrBot，并共享 <code>astrbot-data</code>。</p>
<p>:::steps[单独部署 SnowLuma]</p>
<ol>
<li>
<p><strong>保存配置</strong></p>
<p>SnowLuma 需要先设置 <code>VNC_PASSWD</code>，例如 <code>VNC_PASSWD=passwd123</code>。</p>
<pre><code>services:
  snowluma:
    image: ${SNOWLUMA_IMAGE:-motricseven7/snowluma:latest}
    container_name: ${SNOWLUMA_CONTAINER:-snowluma}
    restart: unless-stopped
    user: "0:0"
    shm_size: 1gb
    cap_add:
      - SYS_PTRACE
    security_opt:
      - seccomp=unconfined
    extra_hosts:
      - "host.docker.internal:host-gateway"
    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: "${SNOWLUMA_EXTRA_QQ_HOMES:-}"
      SNOWLUMA_QQ_FLAGS: "${SNOWLUMA_QQ_FLAGS:---disable-gpu --disable-software-rasterizer --disable-gpu-compositing}"
    ports:
      - "${VNC_PORT:-5900}:5900"
      - "${NOVNC_PORT:-6081}:6081"
      - "${SNOWLUMA_WEBUI_HOST_PORT:-5099}:${SNOWLUMA_WEBUI_PORT:-5099}"
      - "${ONEBOT_HTTP_PORT:-3000}:3000"
      - "${ONEBOT_WS_PORT:-3001}:3001"
    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
</code></pre>
<p>保存为 <code>/opt/astrbot/compose.snowluma.yml</code>。</p>
</li>
<li>
<p><strong>启动</strong></p>
<pre><code>cd /opt/astrbot
docker compose -f compose.snowluma.yml up -d
</code></pre>
</li>
</ol>
<p>:::</p>
<p>:::caution[单独部署的 WebSocket]
SnowLuma 使用 <code>snowluma-network</code> 时，WebSocket 配置见 <a href="/posts/deploy/astrbot-adapter-different-network/">不同网络下的 OneBot WebSocket 通信</a>。</p>
<p><code>astrbot-data</code> 用 <code>external: true</code>，要求 AstrBot 已经创建同名卷；如果 AstrBot 用的是 <code>./data</code>，把挂载改成 <code>/opt/astrbot/data:/AstrBot/data</code>，并删掉顶层 <code>volumes</code> 里的 <code>astrbot-data</code>。
:::</p>
<h2>2.2 AstrBot + SnowLuma 一起部署</h2>
<p>如果还没有单独部署 AstrBot，可以用一份 Compose 把两者一起拉起。两个容器都在 <code>astrbot-network</code>，共享 <code>astrbot-data</code>，<code>6199</code> 不映射到宿主机。</p>
<p>:::steps[一起部署]</p>
<ol>
<li>
<p><strong>保存配置</strong></p>
<p>SnowLuma 需要先设置 <code>VNC_PASSWD</code>，例如 <code>VNC_PASSWD=passwd123</code>。</p>
<pre><code>services:
  astrbot:
    image: soulter/astrbot:latest
    container_name: astrbot
    restart: always
    security_opt:
      - no-new-privileges:true
    ports:
      - "6185:6185" # 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: "0:0"
    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:
      - "${VNC_PORT:-5900}:5900"
      - "${NOVNC_PORT:-6081}:6081"
      - "${SNOWLUMA_WEBUI_HOST_PORT:-5099}:${SNOWLUMA_WEBUI_PORT:-5099}"
      - "${ONEBOT_HTTP_PORT:-3000}:3000"
      - "${ONEBOT_WS_PORT:-3001}:3001"
    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
</code></pre>
<p>保存为 <code>/opt/astrbot/compose.snowluma.yml</code>。</p>
</li>
<li>
<p><strong>启动</strong></p>
<pre><code>cd /opt/astrbot
docker compose -f compose.snowluma.yml up -d
</code></pre>
</li>
</ol>
<p>:::</p>
<p>:::caution[只适用于同一网络]
这份配置依赖 <code>astrbot-network</code> 内部解析。不在同一网络时见 <a href="/posts/deploy/astrbot-adapter-different-network/">不同网络下的 OneBot WebSocket 通信</a>。
:::</p>
<h1>3. 配置 SnowLuma WebSocket</h1>
<p>打开 SnowLuma WebUI。</p>
<p>:::steps[配置 SnowLuma WebSocket]</p>
<ol>
<li>
<p><strong>打开 WebSocket 反向客户端</strong></p>
<p>进入「节点配置 → OneBot 协议端点 → WebSocket 反向客户端」。</p>
</li>
<li>
<p><strong>填写名称</strong></p>
<p>名称填 <code>astrbot</code>。</p>
</li>
<li>
<p><strong>填写 URL</strong></p>
<p>URL 填 <code>ws://astrbot:6199/ws</code>，Token 留空。</p>
</li>
<li>
<p><strong>保存并启用</strong></p>
<p>保存后确认客户端处于启用状态。
:::</p>
</li>
</ol>
<p><img src="/images/posts/deploy/Astrbot/verify/snowluma-websocket-client.png" alt="一起部署的填写示例：ws://astrbot:6199/ws w-100%" title="名称 astrbot，URL ws://astrbot:6199/ws" /></p>
<p>:::tip[不同网络？]
单独部署或跨网络时，见 <a href="/posts/deploy/astrbot-adapter-different-network/">不同网络下的 OneBot WebSocket 通信</a>。
:::</p>
<h1>4. 登录 SnowLuma</h1>
<p>:::steps[登录 SnowLuma]</p>
<ol>
<li>
<p><strong>获取访问令牌</strong></p>
<p>浏览器打开 <code>http://&lt;服务器IP&gt;:5099</code>。首次登录需要访问令牌，令牌在容器日志里：</p>
<pre><code>docker logs snowluma 2&gt;&amp;1 | grep -i -E "webui|token|凭证|访问令牌"
</code></pre>
<p>日志里会打印 WebUI 的访问令牌，不同镜像版本的字段名可能不一样。把它填到登录页：</p>
<p><img src="/images/posts/deploy/Astrbot/verify/snowluma-login.png" alt="SnowLuma WebUI 登录页 w-100%" title="在「输入访问令牌」处填入日志里的 Token" /></p>
</li>
<li>
<p><strong>同意用户协议</strong></p>
<p>首次进入会显示 EULA，勾选「我已阅读并同意」后点「同意并继续」。</p>
<p><img src="/images/posts/deploy/Astrbot/verify/snowluma-eula.png" alt="SnowLuma 首次使用协议 w-100%" title="勾选同意 EULA 后继续" /></p>
</li>
<li>
<p><strong>设置访问密码</strong></p>
<p>按提示设置新的访问密码并确认。</p>
<p><img src="/images/posts/deploy/Astrbot/verify/snowluma-set-password.png" alt="SnowLuma 设置访问密码 w-100%" title="设置并确认新的访问密码" /></p>
</li>
<li>
<p><strong>进入控制台并加载 QQ</strong></p>
<p>设置完成后进入「概览」页；如果 QQ 还没启动，在「进程注入」里加载它，确认状态为「等待登录」。</p>
<p><img src="/images/posts/deploy/Astrbot/verify/snowluma-overview.png" alt="SnowLuma 控制台概览 w-100%" title="在概览页确认服务状态" /></p>
<p><img src="/images/posts/deploy/Astrbot/verify/snowluma-process-injection.png" alt="SnowLuma 进程注入等待登录 w-100%" title="进程注入里显示 qq 等待登录" /></p>
</li>
<li>
<p><strong>登录 noVNC</strong></p>
<p>浏览器打开 <code>http://&lt;服务器IP&gt;:6081</code>，输入 VNC 密码后就能看到 SnowLuma 的桌面，容器会自动启动 QQ。</p>
<p>VNC 密码来自 compose 里的 <code>VNC_PASSWD</code>；没有改过时默认是 <code>vncpasswd</code>。</p>
<p><img src="/images/posts/deploy/Astrbot/verify/snowluma-novnc-credential.webp" alt="noVNC 登录凭证输入框 w-100%" title="输入 VNC_PASSWD，点击发送凭证" /></p>
</li>
<li>
<p><strong>扫码登录 QQ</strong></p>
<p>在桌面里用手机 QQ 扫码登录：</p>
<p><img src="/images/posts/deploy/Astrbot/verify/snowluma-novnc-qq.png" alt="SnowLuma noVNC 中扫码登录 QQ w-100%" title="用手机 QQ 扫描 noVNC 桌面里的二维码" /></p>
<p>登录成功后，回到控制台的「进程注入」，可以看到 QQ 已在线：</p>
<p><img src="/images/posts/deploy/Astrbot/verify/snowluma-qq-online.png" alt="SnowLuma 进程注入显示 QQ 在线 w-100%" title="进程注入里显示 QQ 已在线" />
:::</p>
</li>
</ol>
<p>:::caution[VNC 和 noVNC 不要裸奔]
6081（noVNC）和 5900（VNC 客户端）都能直接操作容器桌面，等于拿到 QQ 的控制权。只给自己使用的 IP 放行，不要把 5900 直接暴露到公网。
:::</p>
<h1>5. 验证连接</h1>
<p>:::steps[验证连接]</p>
<ol>
<li>
<p><strong>看 SnowLuma 概览</strong></p>
<p>「OneBot 连接」里出现 <code>astrbot</code> 的 WS 客户端「已连接」。</p>
<p><img src="/images/posts/deploy/Astrbot/verify/snowluma-overview-connected.png" alt="SnowLuma 概览页显示 astrbot 已连接 w-100%" title="在线账号 1，astrbot WS 客户端已连接" /></p>
</li>
<li>
<p><strong>看 AstrBot 日志</strong></p>
<p>日志里出现 <code>aiocqhttp(OneBot v11) 适配器已连接。</code></p>
<p><img src="/images/posts/deploy/Astrbot/verify/snowluma-astrbot-adapter-connected.png" alt="AstrBot 日志显示 SnowLuma 适配器已连接 w-100%" title="aiocqhttp(OneBot v11) 适配器已连接" />
:::</p>
</li>
</ol>
<h1>常见问题</h1>
<p>::: collapse</p>
<ul>
<li>
<p>SnowLuma 的 WS 客户端一直显示未连接</p>
<p><a href="#22-astrbot--snowluma-%E4%B8%80%E8%B5%B7%E9%83%A8%E7%BD%B2">2.2 一起部署</a>：确认两个容器在同一个 Docker 网络，URL 里的 <code>astrbot</code> 能解析到 AstrBot 容器。</p>
<p>单独部署或跨网络：见 <a href="/posts/deploy/astrbot-adapter-different-network/">不同网络下的 OneBot WebSocket 通信</a>。</p>
</li>
<li>
<p>AstrBot 和 SnowLuma 一起部署时出现 Network 错误</p>
<p>检查 compose 里的网络名是否和 AstrBot 实际使用的网络一致；同一份 compose 里的两个服务必须加入同一个网络。</p>
</li>
<li>
<p>AstrBot 提示 Token 不匹配</p>
<p>AstrBot 的反向 WebSocket Token 和 SnowLuma 的 Token 必须一致；不想校验就两边都留空。</p>
</li>
<li>
<p>SnowLuma 的 VNC 密码在哪里设置</p>
<p>在 <a href="#21-%E5%8D%95%E7%8B%AC%E9%83%A8%E7%BD%B2-snowluma">2.1 单独部署</a> / <a href="#22-astrbot--snowluma-%E4%B8%80%E8%B5%B7%E9%83%A8%E7%BD%B2">2.2 AstrBot + SnowLuma 一起部署</a> 的 Compose 环境变量里设置 <code>VNC_PASSWD</code>。</p>
</li>
</ul>
<p>:::</p>
]]></content>
    <author><name>卟瓿钚</name></author>
    <category term="私有化部署"/>
  </entry>
  <entry>
    <title>AstrBot 在 Linux 上部署</title>
    <link href="https://blog.0v0.uno/posts/deploy/astrbot-linux/" rel="alternate" type="text/html"/>
    <id>https://blog.0v0.uno/posts/deploy/astrbot-linux/</id>
    <published>2026-11-13T15:10:45.000Z</published>
    <updated>2026-11-19T12:48:11.000Z</updated>
    <summary>使用 Docker 在 1panel 上部署 AstrBot</summary>
    <content type="html"><![CDATA[<p>AstrBot 是一个开源的一站式 Agentic 个人和群聊助手，可在 QQ、Telegram、企业微信、飞书、钉钉、Slack 等数十款主流即时通讯软件上部署</p>
<p>这篇假设你已经有一台 Linux 服务器，并且装好了 1Panel 和 Docker。如果还没有，先看系列的前两篇: <a href="/posts/deploy/server/">Linux 海外服务器购买</a> 和 <a href="/posts/deploy/1panel/">1panel安装</a>.</p>
<h1>安装前检查</h1>
<h2>查看端口</h2>
<p>部署前先确认端口。1Panel 防火墙和云厂商安全组是两层，==任意一层没放行，浏览器都打不开=={.error}。下面这些端口统一使用 <code>TCP</code>：</p>
<table>
<thead>
<tr>
<th>端口</th>
<th>用途</th>
<th>何时开放</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>6185</code></td>
<td>AstrBot WebUI</td>
<td>必开，用于浏览器访问 AstrBot 后台</td>
</tr>
</tbody>
</table>
<p>在 1Panel 中进入「主机 → 防火墙」，点击「创建」，类型选「自定义」，协议选 <code>TCP</code>，端口填 <code>6185</code>。来源尽量限制为自己的 IP，备注写清楚用途。</p>
<p>:::tip[云厂商防火墙]
注意是在你购买服务器的地方放行端口
:::</p>
<h1>在 1panel 中可视化安装</h1>
<p>:::info
没有安装 1panel 请先安装 <a href="/posts/deploy/1panel/">1panel</a>.</p>
<p>下面的两种安装方式, <strong>选择一种</strong>即可
:::</p>
<h2>单独安装 Astrbot 容器</h2>
<p>只跑一个 AstrBot 容器时，不需要写 Compose。按 ==网络 → 存储卷 → 容器=={.primary} 的顺序建三样东西即可。</p>
<p>先按网络环境选镜像地址：</p>
<p>:::tabs</p>
<p>@tab 国内</p>
<p><code>m.daocloud.io/docker.io/soulter/astrbot:latest</code></p>
<p>@tab 国外</p>
<p><code>soulter/astrbot:latest</code></p>
<p>:::</p>
<p>:::steps[单独安装 AstrBot 容器]</p>
<ol>
<li>
<p><strong>创建网络</strong></p>
<p>在左侧进入「容器」，切到顶部的「网络」，点击「创建」。</p>
<table>
<thead>
<tr>
<th>配置项</th>
<th>填写</th>
</tr>
</thead>
<tbody>
<tr>
<td>名称</td>
<td><code>astrbot-network</code></td>
</tr>
<tr>
<td>模式</td>
<td><code>bridge</code></td>
</tr>
<tr>
<td>子网</td>
<td><code>172.19.0.0/16</code></td>
</tr>
<tr>
<td>网关</td>
<td><code>172.19.0.1</code></td>
</tr>
<tr>
<td>IPv6</td>
<td>关闭</td>
</tr>
</tbody>
</table>
<p><code>172.17.0.0/16</code> 是 Docker 默认 bridge，<code>172.18.0.0/16</code> 是 1Panel 自带的 <code>1panel-network</code>，所以这里用 ==<code>172.19.0.0/16</code>=={.primary}，不要和宿主机局域网、VPN 或其他 Docker 网络重叠。只跑 AstrBot 和几个适配器，用 <code>/24</code> 也够。</p>
<p><img src="/images/posts/deploy/Astrbot/1panel/1panel-network-create.png" alt="1Panel 创建 astrbot-network 网络 w-100%" title="名称 astrbot-network，模式 bridge，子网 172.19.0.0/16，网关 172.19.0.1" /></p>
</li>
<li>
<p><strong>创建存储卷</strong></p>
<p>切到顶部的「存储卷」，点击「创建」，名称填 ==<code>astrbot-data</code>=={.primary}。</p>
<p>命名卷由 Docker 管理，删除容器不会丢数据，权限问题也少；本机目录方便查看文件，但容易出现 UID/GID 权限问题。这里用命名卷。</p>
<p>创建后点开详情，挂载点是 <code>/var/lib/docker/volumes/astrbot-data/_data</code>。</p>
<p><img src="/images/posts/deploy/Astrbot/1panel/1panel-volume-create.png" alt="1Panel 创建 astrbot-data 存储卷 w-100%" title="创建名为 astrbot-data 的存储卷，详情里可以看到 Docker 的挂载路径" /></p>
</li>
<li>
<p><strong>填写基本信息</strong></p>
<p>回到「容器」页面，点击「创建」。</p>
<p>名称填 <code>astrbot</code>，镜像勾选「手动输入」，填上面选中的地址。</p>
<p>端口选「暴露端口」，添加 <code>6185:6185/tcp</code>。</p>
<p>「强制拉取镜像」首次安装可以不勾，更新镜像时勾上；「容器退出后自动删除容器」==不要勾选=={.error}。</p>
<p><img src="/images/posts/deploy/Astrbot/1panel/1panel-container-create.png" alt="1Panel 创建 astrbot 容器的基本信息 w-100%" title="名称 astrbot，镜像 soulter/astrbot:latest，暴露 6185 端口" /></p>
</li>
<li>
<p><strong>配置网络</strong></p>
<p>选择 ==<code>astrbot-network</code>=={.primary}；MAC 地址、IPv4、IPv6、主机名、Domain、DNS 都留空，让 Docker 自动分配。</p>
<p><img src="/images/posts/deploy/Astrbot/1panel/1panel-container-network.png" alt="1Panel 容器网络选择 astrbot-network w-100%" title="在容器的网络标签中选择 astrbot-network" /></p>
</li>
<li>
<p><strong>配置挂载</strong></p>
<p>添加三条挂载：</p>
<table>
<thead>
<tr>
<th>类型</th>
<th>服务器</th>
<th>容器目录</th>
<th>权限</th>
</tr>
</thead>
<tbody>
<tr>
<td>挂载卷</td>
<td><code>astrbot-data</code></td>
<td><code>/AstrBot/data</code></td>
<td>读写</td>
</tr>
<tr>
<td>本机目录</td>
<td><code>/etc/localtime</code></td>
<td><code>/etc/localtime</code></td>
<td>只读</td>
</tr>
<tr>
<td>本机目录</td>
<td><code>/etc/timezone</code></td>
<td><code>/etc/timezone</code></td>
<td>只读</td>
</tr>
</tbody>
</table>
<p>第一条把命名卷挂到数据目录；后两条同步宿主机时区。==<code>/etc/localtime</code> 和 <code>/etc/timezone</code> 都选只读=={.tip}。</p>
<p><img src="/images/posts/deploy/Astrbot/1panel/1panel-container-mount.png" alt="1Panel 容器挂载数据卷和时区文件 w-100%" title="astrbot-data 挂载到 /AstrBot/data，localtime 和 timezone 以本机目录方式挂载，权限都选只读" /></p>
</li>
<li>
<p><strong>设置环境变量</strong></p>
<p>添加环境变量 ==<code>TZ=Asia/Shanghai</code>=={.primary}。</p>
<p><img src="/images/posts/deploy/Astrbot/1panel/1panel-container-env.png" alt="1Panel 容器环境变量设置时区 w-100%" title="添加环境变量 TZ=Asia/Shanghai" /></p>
</li>
<li>
<p><strong>重启规则</strong></p>
<p>这里对重启规则没有要求，随便选都可以。
:::</p>
</li>
</ol>
<h2>使用 compose 单独安装 Astrbot</h2>
<p>:::tip[想使用 compose 安装 Astrbot?]
Compose的优势就是可以多个容器一起部署而且不需要上面的各种设置,一键启动即可.见 <a href="/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">NapCat 一起部署</a> 和 <a href="/posts/deploy/astrbot-adapter-snowluma/#22-astrbot--snowluma-%E4%B8%80%E8%B5%B7%E9%83%A8%E7%BD%B2">SnowLuma 一起部署</a>。</p>
<p>问题是: 不同容器出现问题时, compose需要同时重启, 这个比较麻烦, 所以更推荐容器安装, 然后手动调整
:::</p>
<p>:::steps[在 1Panel 中创建编排]</p>
<ol>
<li>
<p><strong>打开编排创建页</strong></p>
<p>在 1Panel 中进入「编排 → 创建」，来源选「编辑」，名称填 <code>astrbot</code>。</p>
<p><img src="/images/posts/deploy/Astrbot/1panel/1panel-compose-create.png" alt="1Panel 编排创建页：来源选编辑，名称填 astrbot，粘贴 YAML 后保存 w-100%" title="1Panel 编排创建页" /></p>
</li>
<li>
<p><strong>粘贴 YAML</strong></p>
<p>YAML 中使用了 <code>astrbot-network</code>，请先确认这个网络是否存在：</p>
<ul>
<li>不存在：保留 <code>driver: bridge</code>，Compose 会创建网络（实际名称可能带项目前缀）。</li>
<li>已存在：注释 <code>driver: bridge</code>，取消 <code>external: true</code> 的注释，复用已有网络。</li>
</ul>
<p>上面的截图仅展示 1Panel 编排创建页的填写方式，截图里的 YAML ==没有=={.primary} 包含这段 <code>networks</code> 配置。</p>
<pre><code>services:
  astrbot:
    image: soulter/astrbot:latest
    container_name: astrbot
    restart: always
    security_opt:
      - no-new-privileges:true
    ports:
      - "6185:6185" # 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
</code></pre>
</li>
<li>
<p><strong>保存并启动</strong></p>
<p>点击「保存」，1Panel 会按这份编排创建容器。
:::</p>
</li>
</ol>
<h1>完成界面</h1>
<p>部署完成后，浏览器打开 <code>http://&lt;服务器IP&gt;:6185</code>，用日志里的初始密码登录。</p>
<table>
<thead>
<tr>
<th>界面</th>
<th>默认地址</th>
<th>凭证</th>
</tr>
</thead>
<tbody>
<tr>
<td>AstrBot WebUI</td>
<td><code>http://&lt;服务器IP&gt;:6185</code></td>
<td>日志中的 <code>Initial Password</code></td>
</tr>
</tbody>
</table>
<p>:::steps[第一次登录]</p>
<ol>
<li>
<p><strong>获取初始密码</strong></p>
<p>1Panel 里进入「容器」→ <code>astrbot</code> → 「日志」；或者命令行执行：</p>
<pre><code>docker logs astrbot 2&gt;&amp;1 | grep -i "password"
</code></pre>
<p>首次启动的日志里会出现 <code>Initial Password: xxxxxxxx</code>，用户名通常是 <code>astrbot</code>。</p>
<p><img src="/images/posts/deploy/Astrbot/verify/astrbot-initial-password.png" alt="1Panel 中 AstrBot 启动日志里的初始用户名和密码 w-100%" title="AstrBot v4.29.4 WebUI is ready，下面会打印 Initial username 和 Initial password" /></p>
<p>截图中的密码仅作示例，请以自己日志里的值为准。</p>
</li>
<li>
<p><strong>登录 WebUI</strong></p>
<p>浏览器打开 <code>http://&lt;服务器IP&gt;:6185</code>，用 <code>astrbot</code> 和初始密码登录。打不开时先回看「查看端口」，确认 1Panel 防火墙和云厂商安全组都已放行 6185。</p>
<p><img src="/images/posts/deploy/Astrbot/verify/astrbot-login.png" alt="AstrBot WebUI 登录页 w-100%" title="用户名 astrbot，密码填日志里的 Initial password" /></p>
</li>
<li>
<p><strong>修改密码并进入首页</strong></p>
<p>登录后第一件事是改密码。6185 暴露在公网时，面板可以配置模型密钥、消息平台和插件，尽量不要把它开放给所有人。</p>
<p><img src="/images/posts/deploy/Astrbot/verify/astrbot-dashboard.png" alt="AstrBot WebUI 首页 w-100%" title="在快速引导里继续配置模型和消息平台" />
:::</p>
</li>
</ol>
<h1>常见问题</h1>
<p>::: collapse</p>
<ul>
<li>
<p>部署完成后为什么无法访问 6185 端口</p>
<p>大概率是因为你没有在服务器厂商那里把==防火墙=={.primary}端口打开</p>
</li>
<li>
<p>想和 NapCat/SnowLuma 一起部署？</p>
<p>见 <a href="/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">NapCat 一起部署</a> 和 <a href="/posts/deploy/astrbot-adapter-snowluma/#22-astrbot--snowluma-%E4%B8%80%E8%B5%B7%E9%83%A8%E7%BD%B2">SnowLuma 一起部署</a>。</p>
</li>
</ul>
<p>:::</p>
<h1>参考资料</h1>
<ul>
<li>AstrBot Docker 部署：https://docs.astrbot.app/deploy/astrbot/docker.html</li>
</ul>
]]></content>
    <author><name>卟瓿钚</name></author>
    <category term="私有化部署"/>
  </entry>
  <entry>
    <title>1Panel 安装与初始化</title>
    <link href="https://blog.0v0.uno/posts/deploy/1panel/" rel="alternate" type="text/html"/>
    <id>https://blog.0v0.uno/posts/deploy/1panel/</id>
    <published>2026-11-12T03:25:08.000Z</published>
    <updated>2026-11-12T03:25:08.000Z</updated>
    <summary>在 Linux 服务器上安装 1Panel，完成初始化、安全设置和 Docker 环境准备。</summary>
    <content type="html"><![CDATA[<p>1Panel 是飞致云开源的 Linux 运维面板，官方网站为 <a href="https://1panel.cn/">1panel.cn</a>，官方文档位于 <a href="https://1panel.cn/docs/">1panel.cn/docs</a>。它把 Docker、应用商店、网站、防火墙、文件管理和计划任务集中到一个 Web 界面。</p>
<p>这篇从一台刚买到的 Linux 服务器开始，装好 1Panel 并完成必要的安全设置。</p>
<h2>1. 安装前准备</h2>
<h3>1.1 系统要求</h3>
<ul>
<li><strong>系统</strong>：主流 Debian/RedHat 系 Linux，包括 Ubuntu、Debian、CentOS、Rocky Linux、AlmaLinux、openEuler 等。</li>
<li><strong>架构</strong>：x86_64、aarch64、armv7l 等。</li>
<li><strong>内存</strong>：建议可用内存 2 GB 以上</li>
<li><strong>权限</strong>：root 或具有 sudo 权限的用户。</li>
<li><strong>网络</strong>：能访问外网；内网环境需要使用离线安装包。</li>
</ul>
<p>先更新系统，Ubuntu/Debian 使用：</p>
<pre><code>apt update &amp;&amp; apt upgrade -y
</code></pre>
<p>CentOS 7 使用：</p>
<pre><code>yum update -y
</code></pre>
<p>CentOS Stream 8/9、Rocky Linux、AlmaLinux 使用：</p>
<pre><code>dnf update -y
</code></pre>
<h3>1.2 安装前放行面板端口</h3>
<p>先确定 1Panel 面板端口为 <code>12345</code>，并在安装前放行。端口统一在服务器厂商控制台的安全组或防火墙页面中设置：</p>
<table>
<thead>
<tr>
<th>用途</th>
<th>端口</th>
</tr>
</thead>
<tbody>
<tr>
<td>SSH</td>
<td><code>22</code></td>
</tr>
<tr>
<td>1Panel 面板</td>
<td><code>12345</code></td>
</tr>
</tbody>
</table>
<p>找到实例对应的安全组或防火墙，新增一条入站规则：协议选择 <code>TCP</code>，端口填写 <code>12345</code>。如果知道访问面板的公网 IP，来源地址应只允许该 IP；不要把面板端口无条件开放给整个互联网。</p>
<p>以京东云为例，进入轻量应用服务器的设置界面，在“防火墙”页面点击“添加规则”，协议选择 <code>TCP</code>，目标端口填写 <code>12345</code>，保存后即可放行面板端口。</p>
<p><img src="/images/posts/deploy/1panel/jd-cloud-firewall.png" alt="京东云轻量应用服务器防火墙中添加 TCP 12345 规则 w-100%" title="在京东云防火墙中放行 1Panel 面板端口" /></p>
<h2>2. 在线安装</h2>
<p>1Panel v2 提供一键安装脚本，它会自动检测服务器的架构，然后下载对应的版本。使用 root 或 sudo 执行：</p>
<pre><code>bash -c "$(curl -sSL https://resource.fit2cloud.com/1panel/package/v2/quick_start.sh)"
</code></pre>
<p>脚本会依次询问：</p>
<p>:::steps[交互式安装流程]</p>
<ol>
<li>
<p><strong>安装目录</strong></p>
<p>默认 <code>/opt</code>，没有特殊需求直接回车。</p>
<pre><code>[1Panel 2026-11-12 10:48:26 install Log]: ==== 开始安装 ====
设置 1Panel 安装目录（默认：/opt）：
[1Panel 2026-11-12 10:48:31 install Log]: 已选择安装路径： /opt
</code></pre>
</li>
<li>
<p><strong>安装 Docker</strong></p>
<p>安装 1Panel 的过程中会检测是否安装 Docker。没有安装 Docker 时会询问是否需要安装，一般选择 <code>y</code>。</p>
<p>安装脚本会自动安装 Docker。</p>
<pre><code>检测到未安装 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 &gt;/dev/null
   + sh -c DEBIAN_FRONTEND=noninteractive apt-get -y -qq install ca-certificates curl &gt;/dev/null
   + sh -c install -m 0755 -d /etc/apt/keyrings
   + sh -c curl -fsSL "https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg" -o /etc/apt/keyrings/docker.asc
   + sh -c chmod a+r /etc/apt/keyrings/docker.asc
   + sh -c echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.asc] https://mirrors.aliyun.com/docker-ce/linux/ubuntu noble stable" &gt; /etc/apt/sources.list.d/docker.list
   + sh -c apt-get -qq update &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 &gt;/dev/null
   Using systemd to manage Docker service
   + sh -c systemctl enable --now docker.service 2&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 'Docker daemon attack surface'
            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 服务已成功重启。
</code></pre>
</li>
<li>
<p><strong>面板端口</strong></p>
<p>输入已经放行的 <code>12345</code>。</p>
<pre><code>   设置 1Panel 端口（默认： &lt;随机端口&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)
</code></pre>
</li>
<li>
<p><strong>安全入口</strong></p>
<p>相当于面板 URL 的隐藏路径，例如 <code>panel-a1b2c3</code>。不要用 <code>admin</code>、<code>login</code> 这类容易猜到的值。</p>
<blockquote>
<p>[!TIP]
建议安全入口跟后续设置的用户名保持一致，方便记忆。例如安全入口设为 <code>panel-a1b2c3</code>，最终访问地址就是 <code>http://&lt;服务器IP&gt;:&lt;端口&gt;/panel-a1b2c3</code>。</p>
</blockquote>
<pre><code>   设置 1Panel 安全入口（默认： &lt;随机安全入口&gt;): &lt;自定义安全入口&gt;
   [1Panel 2026-11-12 10:54:34 install Log]: 已设置面板安全入口： &lt;已隐藏&gt;
</code></pre>
</li>
<li>
<p><strong>用户名和密码</strong></p>
<p>用户名 3–30 位字母、数字或下划线；密码 8–30 位，支持字母、数字和 <code>_!@#$%*,.?</code>。建议用密码管理器生成。</p>
</li>
<li>
<p><strong>是否配置镜像加速</strong></p>
<p>国内服务器建议选 <code>y</code>；如果已经有可用的加速配置，选 <code>n</code> 以免覆盖。
:::</p>
</li>
</ol>
<p>安装完成后，终端会打印访问地址，格式为：</p>
<pre><code>   [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://&lt;服务器公网IP&gt;:12345/&lt;安全入口&gt;
   [1Panel 2026-11-12 10:54:48 install Log]: 内部地址： http://&lt;服务器内网IP&gt;:12345/&lt;安全入口&gt;
   [1Panel 2026-11-12 10:54:48 install Log]: 面板用户： &lt;已隐藏&gt;
   [1Panel 2026-11-12 10:54:48 install Log]: 面板密码： &lt;已隐藏&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]: ================================================================
</code></pre>
<h2>3. 内网离线安装</h2>
<p>服务器不能访问公网时，可以使用 1Panel V2 离线包。离线包已预置 Docker 和常用应用镜像，不需要在安装过程中下载依赖。</p>
<p>:::important[离线安装的是企业试用版]
1Panel 离线安装包已集成企业版核心功能。安装完成后会进入 7 天企业版全功能试用期，并不会直接安装为社区版。试用结束后，登录页会要求导入许可证，需要手动恢复社区版。
:::</p>
<h3>3.1 获取官方离线包</h3>
<p>前往 <a href="https://community.fit2cloud.com/#/products/1panel/downloads">FIT2CLOUD 开源社区下载页面</a> 下载 1Panel 企业版离线安装包。官方文档目前提供 x86_64（amd64）架构的离线包，用于首次安装和后续升级。</p>
<p>:::warning[升级和恢复使用不同安装包]
企业版离线包可以用于安装和升级。试用到期后恢复社区版时，不能继续使用这个离线包，需要在登录页点击“复制下载链接”，重新下载版本不低于当前企业版的社区版安装包。
:::</p>
<p>具体内容以 <a href="https://docs.fit2cloud.com/1panel/installation/enterprise-installation">1Panel 官方离线安装文档</a> 为准。</p>
<h3>3.2 上传并安装</h3>
<p>先在内网可访问的跳板机或管理机上准备离线包，然后上传到目标服务器。以下载到当前目录的 <code>1panel-v2.x.x-offline-linux-amd64.tar.gz</code> 为例：</p>
<pre><code>scp 1panel-v2.x.x-offline-linux-amd64.tar.gz root@&lt;服务器IP&gt;:/tmp/
</code></pre>
<p>SSH 登录内网服务器，以 root 用户解压并运行安装脚本：</p>
<pre><code>cd /tmp
tar -zxvf 1panel-v2.x.x-offline-linux-amd64.tar.gz
cd 1panel-v2.x.x-offline-linux-amd64
bash install.sh
</code></pre>
<p>安装脚本提示设置面板端口时输入 <code>12345</code>。安装目录、安全入口、用户名、密码和 Docker 选项与在线安装一致。安装完成后，在浏览器访问：</p>
<pre><code>http://&lt;服务器IP&gt;:12345/&lt;安全入口&gt;
</code></pre>
<h3>3.3 试用到期后恢复社区版</h3>
<p>7 天企业版试用结束后，1Panel 不会自动切回社区版。面板仍会要求导入许可证，需要按以下步骤手动恢复：</p>
<p>:::steps[恢复社区版]</p>
<ol>
<li>
<p><strong>打开登录页</strong></p>
<p>浏览器访问 1Panel 登录页面。</p>
</li>
<li>
<p><strong>选择恢复社区版</strong></p>
<p>单击登录页右上角的 <strong>恢复社区版</strong>。</p>
</li>
<li>
<p><strong>选择恢复方式</strong></p>
<p>在弹窗中选择恢复方式：</p>
<ul>
<li>服务器可以访问互联网时，选择 <strong>在线恢复</strong>。</li>
<li>内网或服务器无法访问外网时，选择 <strong>离线恢复</strong>。</li>
</ul>
</li>
<li>
<p><strong>复制社区版下载链接</strong></p>
<p>选择 <strong>离线恢复</strong> 后，在弹窗中单击 <strong>复制下载链接</strong>。社区版安装包会使用这个链接下载，版本不能低于当前企业版。</p>
<p>这一步需要在能访问互联网的设备上完成，因为内网服务器无法直接下载。</p>
</li>
<li>
<p><strong>上传社区版安装包</strong></p>
<p>将下载得到的社区版安装包上传到服务器的恢复目录。目录不存在时先创建：</p>
<pre><code>mkdir -p /opt/1panel/tmp/community-restore
</code></pre>
<p>从其他设备上传安装包：</p>
<pre><code>scp &lt;社区版安装包&gt; root@&lt;服务器IP&gt;:/opt/1panel/tmp/community-restore/
</code></pre>
</li>
<li>
<p><strong>确认恢复</strong></p>
<p>确认社区版安装包已经放入 <code>/opt/1panel/tmp/community-restore</code>，然后回到恢复弹窗单击 <strong>确认</strong>。</p>
</li>
<li>
<p><strong>重新登录</strong></p>
<p>切换完成后，使用恢复前的企业版超级管理员账号和密码登录。
:::</p>
</li>
</ol>
<p>:::warning[不要放入企业版离线包]
恢复社区版时，不能把第 3.1 节下载的企业版离线包放入 <code>/opt/1panel/tmp/community-restore</code>。放错文件后切换过程仍可能执行完成，但面板依然是企业版，再次登录仍会回到许可证页面，账号和密码也可能被重置为 <code>username</code> 和 <code>password</code>。</p>
<p>如果账号已经被重置，可以在服务器上重新设置：</p>
<pre><code>1pctl update username
1pctl update password
</code></pre>
<p>:::</p>
<p>:::note[版本切换后的数据]
恢复社区版会清除企业版专属数据，基础功能可以继续使用。切换完成后，使用恢复前的企业版超级管理员账号登录社区版。
:::</p>
<h2>4. 常用命令</h2>
<pre><code>1pctl user-info
1pctl status
1pctl restart
</code></pre>
<ul>
<li><code>1pctl user-info</code>：查看面板地址、安全入口和用户名。</li>
<li><code>1pctl status</code>：查看 1Panel 服务状态。</li>
<li><code>1pctl restart</code>：重启面板服务。</li>
</ul>
<p>升级面板在 Web 界面右下角检查更新，或按官方文档执行升级命令。升级前先做快照。</p>
<h2>5. 常见问题</h2>
<p>::: collapse</p>
<ul>
<li>
<p><strong>面板打不开</strong></p>
<p>按顺序检查：</p>
<ol>
<li>服务器厂商的安全组或防火墙是否放行 <code>TCP 12345</code>；</li>
<li>安装时是否将面板端口设置为 <code>12345</code>；</li>
<li><code>1pctl status</code> 是否显示服务正常；</li>
<li>访问地址是否包含安全入口；</li>
<li>本机能否访问：<code>curl -I http://127.0.0.1:12345</code>。</li>
</ol>
</li>
<li>
<p><strong>Docker 安装失败</strong></p>
<p>可以尝试使用镜像站脚本单独安装 Docker：</p>
<pre><code>bash &lt;(curl -sSL https://linuxmirrors.cn/docker.sh)
</code></pre>
<p>安装完成后回到 1Panel 容器页面确认状态。</p>
</li>
<li>
<p><strong>忘记安全入口</strong></p>
<pre><code>1pctl user-info
</code></pre>
</li>
<li>
<p><strong>拉取镜像很慢</strong></p>
<p>优先配置镜像加速；其次在 Compose 文件中把镜像地址替换为带加速前缀的地址。不要同时配置多个互相冲突的加速源。
:::</p>
</li>
</ul>
<h2>6. 参考资料</h2>
<ul>
<li>1Panel 在线安装：https://1panel.cn/docs/v2/installation/online_installation/</li>
<li>1Panel 离线安装：https://docs.fit2cloud.com/1panel/installation/enterprise-installation</li>
<li>1Panel 命令行工具：https://1panel.cn/docs/v2/installation/cli/</li>
</ul>
]]></content>
    <author><name>卟瓿钚</name></author>
    <category term="私有化部署"/>
  </entry>
  <entry>
    <title>服务器选购(海外)</title>
    <link href="https://blog.0v0.uno/posts/deploy/server/" rel="alternate" type="text/html"/>
    <id>https://blog.0v0.uno/posts/deploy/server/</id>
    <published>2026-11-11T13:20:00.000Z</published>
    <updated>2026-11-11T16:00:05.000Z</updated>
    <summary>腾讯云的新加坡与美国轻量服务器：30M 起步，直连海外 API，适合长期在线的业务。</summary>
    <content type="html"><![CDATA[<p>选海外服务器时，国内机器不是不能跑，而是不划算：带宽通常只有 1–5 Mbps，访问 OpenAI、Gemini、Claude 等海外服务往往得再维护一层代理。</p>
<p>把机器放到==新加坡或美国=={.primary}，带宽直接上到 30 Mbps 起步，海外 API 直连，省掉代理的麻烦。这篇只讲腾讯云的新加坡和美国节点，以及不同用途该怎么选配置。</p>
<h2>1. 为什么是新加坡和美国</h2>
<h3>1.1 新加坡</h3>
<p>新加坡是==亚太的网络枢纽=={.primary}，海底光缆密集，到世界各地都有直连线路：</p>
<ul>
<li>到中国大陆约 60–90 ms，到东南亚约 20–50 ms，到美西约 150–200 ms。</li>
<li>对 OpenAI、Gemini、Claude 等海外 API 通常可以直连，不需要在服务器上再跑代理。</li>
<li>适合挂 QQ、Telegram、Discord 机器人，也适合面向亚太用户的网站。</li>
</ul>
<p>缺点是晚高峰到中国大陆的线路可能拥堵，热门套餐也==经常缺货=={.error}。腾讯云新加坡轻量就属于经常抢不到的地域。</p>
<h3>1.2 美国</h3>
<p>美国节点主要有==硅谷和弗吉尼亚=={.primary}两个方向：</p>
<ul>
<li>到中国大陆约 150–220 ms，延迟比新加坡高，但==带宽充足、价格低、库存稳定=={.tip}。</li>
<li>访问美国本土 API 的延迟最低，适合 OpenAI、Anthropic 以及各种美国服务。</li>
<li>适合对延迟不敏感、但流量较大的场景：机器人、下载、镜像、备份。</li>
</ul>
<p>国内用户打开美国机器的 Web 面板会明显变慢，但大多数后台任务和 API 调用对这点延迟不敏感，实际使用没有太大区别。</p>
<h3>1.3 其他地区</h3>
<table>
<thead>
<tr>
<th>地区</th>
<th>特点</th>
<th>结论</th>
</tr>
</thead>
<tbody>
<tr>
<td>新加坡</td>
<td>亚太枢纽，国内延迟低，国际线路好</td>
<td>==首选=={.primary}</td>
</tr>
<tr>
<td>美国硅谷</td>
<td>带宽大、库存稳、美国 API 延迟低</td>
<td>==首选=={.primary}</td>
</tr>
<tr>
<td>中国香港</td>
<td>国内延迟最低，但带宽贵、国际出口一般</td>
<td>==预算充足再考虑=={.secondary}</td>
</tr>
<tr>
<td>日本、韩国</td>
<td>延迟低，但大厂套餐少、线路稳定性一般</td>
<td>==不作为首选=={.tertiary}</td>
</tr>
<tr>
<td>欧洲</td>
<td>到国内延迟高，适合欧洲用户</td>
<td>按用户分布选择</td>
</tr>
</tbody>
</table>
<p>对大多数在线服务来说，==100–200 ms 的延迟完全可用=={.tip}。真正影响体验的是带宽和流量，所以优先选 30 Mbps 以上的套餐，而不是纠结那几十毫秒。</p>
<h2>2. 大厂套餐怎么选</h2>
<p>海外服务器目前只推荐==腾讯云=={.primary}。它的国际线路、库存和售后比较稳定，价格也透明；其它厂商要么活动少，要么热门地域经常缺货。</p>
<h3>2.1 腾讯云轻量应用服务器</h3>
<p>腾讯云的海外轻量（<a href="https://cloud.tencent.com/product/lighthouse">Lighthouse</a>）==活动最频繁=={.primary}，新加坡和硅谷同价。</p>
<table>
<thead>
<tr>
<th>项目</th>
<th>参考配置</th>
</tr>
</thead>
<tbody>
<tr>
<td>CPU / 内存</td>
<td>2 核 2 GB（入门），2 核 4 GB（推荐）</td>
</tr>
<tr>
<td>带宽</td>
<td>30 Mbps 峰值</td>
</tr>
<tr>
<td>系统盘</td>
<td>50–60 GB SSD</td>
</tr>
<tr>
<td>月流量</td>
<td>1–1.5 TB</td>
</tr>
<tr>
<td>地域</td>
<td>新加坡、美国硅谷、东京、首尔、法兰克福等</td>
</tr>
</tbody>
</table>
<p>价格分两种渠道：</p>
<p>:::tabs</p>
<p>@tab 中国站</p>
<p>海外地域活动价常见 <code>99 元/年</code>（2C2G/30M/1TB）和 <code>199 元/年</code>（2C4G/30M/1.5TB），支持支付宝，需要实名。购买和续费尽量走<a href="https://cloud.tencent.com/act?Is=sdk-topnav">腾讯云活动页</a>，活动页通常提供一次“==同价续费=={.tip}”；==不要直接按日常价续费=={.error}，控制台直接续费是原价，差价很大。</p>
<p>@tab 国际站</p>
<p>2C2G/30M/1TB 约 <code>$4.9–5.2/月</code>，活动款曾出现 <code>$10.08/年</code>（2C2G/20M/512GB）。国际站用美元结算，支持信用卡。</p>
<p>:::</p>
<p>中国站的 <code>199 元/年</code>（2C4G/30M/1.5TB，硅谷）是==日常折扣价=={.secondary}，日常价 504 元/年；到了 1024 程序员节、双 11 这类节点，同档可低至 ==79 元/年=={.primary} 左右。不急用可以等活动，急用再按 199 元买。</p>
<p>:::tip[按月购买]
不走活动直接月付时，镜像选 ==Ubuntu LTS=={.primary}（系统干净，后面装 1Panel 和 Docker 少踩坑），规格选入门型或锐驰型：入门型便宜、带宽低，锐驰型是 200M 峰值不限流量。==2C4G=={.primary}、带宽按需选择，月付控制在 ==60 元以内=={.tip} 就很划算。地域优先==新加坡二区=={.primary}，部分时段国内访问质量不错，但官方不承诺直连，晚高峰仍可能拥堵。
:::</p>
<p>线路方面，新加坡和硅谷走中国电信 CN2、联通 AS4837、移动 CMI/CMNET。社区反馈硅谷晚高峰更稳，新加坡更容易拥堵；新加坡和东京经常缺货，硅谷库存相对充足。</p>
<h3>2.2 套餐小结</h3>
<table>
<thead>
<tr>
<th>厂商</th>
<th>产品</th>
<th>入门配置</th>
<th>带宽 / 流量</th>
<th>参考价</th>
</tr>
</thead>
<tbody>
<tr>
<td>腾讯云</td>
<td>轻量 Lighthouse</td>
<td>2C2G / 50G</td>
<td>30M 峰值 / 1TB 月流量</td>
<td>中国站 99 元/年起；国际站约 $5/月</td>
</tr>
</tbody>
</table>
<p>:::tip[选购顺序]
先用地域筛掉不合适的节点，再用内存筛掉不够用的配置，最后比较中国站和国际站的价格。地域选错只能迁移，配置不够还可以升。
:::</p>
<h2>3. 配置怎么选</h2>
<h3>3.1 内存优先</h3>
<p>这类在线服务通常不跑本地模型推理，真正吃资源的是系统、<a href="/posts/deploy/1panel/">1Panel</a>、Docker 和常驻进程。内存按实际运行的容器数量估算：</p>
<table>
<thead>
<tr>
<th>场景</th>
<th>建议配置</th>
</tr>
</thead>
<tbody>
<tr>
<td>单个轻量服务 + 1Panel</td>
<td>2 核 2 GB</td>
</tr>
<tr>
<td>多个 Docker 容器、反向代理、数据库</td>
<td>2 核 4 GB</td>
</tr>
<tr>
<td>多个业务实例、代码沙盒</td>
<td>4 核 4 GB 以上</td>
</tr>
</tbody>
</table>
<p>==不要买 1 核 1 GB=={.error}。系统、Docker 和面板会吃掉大半内存，更新镜像或同时跑两个容器时很容易 OOM。2 GB 内存建议再加 ==1–2 GB swap=={.tip} 兜底。</p>
<h3>3.2 磁盘和带宽</h3>
<ul>
<li><strong>系统盘 40 GB 起步</strong>：Docker 镜像、日志、业务数据和备份都会持续增长，60 GB 更从容。</li>
<li><strong>带宽 30 Mbps 足够</strong>：纯文本服务每月的流量通常只有几 GB，1 TB 的月流量包基本用不完；图片、文件下载和大流量业务才会明显消耗流量。</li>
<li><strong>流量超额</strong>：腾讯云约 <code>$0.077–0.081/GB</code>，注意套餐的流量包大小。</li>
</ul>
<h3>3.3 地域怎么选</h3>
<ul>
<li>主要面向国内用户：优先==新加坡=={.primary}，延迟比美国低。</li>
<li>主要调用 OpenAI、Anthropic 等美国 API：==硅谷=={.primary}更合适，延迟最低。</li>
<li>同时服务国内和海外用户：新加坡折中。</li>
<li>只调用 DeepSeek、通义千问、Kimi 等国内 API，且用户都在国内：国内服务器延迟低，但带宽低，选购见<a href="/posts/deploy/server-cn/">国内轻量服务器优惠汇总</a>。</li>
<li>新加坡和美国通常在 OpenAI、Gemini、Anthropic 的支持地区列表内，购买前以官方列表为准。</li>
</ul>
<p>:::info[国内服务器与备案]
国内低价轻量服务器见<a href="/posts/deploy/server-cn/">国内轻量服务器优惠汇总</a>；ICP 备案流程见<a href="/posts/deploy/icp-filing/">ICP 备案指南</a>。这两篇是独立文章，不在本系列里。
:::</p>
<h2>4. 总结</h2>
<table>
<thead>
<tr>
<th>决策点</th>
<th>建议</th>
</tr>
</thead>
<tbody>
<tr>
<td>地域</td>
<td>==首选新加坡=={.primary}；要稳定库存或美国 API 选硅谷</td>
</tr>
<tr>
<td>厂商</td>
<td>腾讯云</td>
</tr>
<tr>
<td>配置</td>
<td>2 核 2 GB 起步，2 核 4 GB 更稳</td>
</tr>
<tr>
<td>带宽</td>
<td>30 Mbps 起步；要大带宽选锐驰型</td>
</tr>
<tr>
<td>流量</td>
<td>1 TB/月足够，注意超额单价</td>
</tr>
<tr>
<td>系统盘</td>
<td>40 GB 起步，60 GB 更从容</td>
</tr>
<tr>
<td>系统</td>
<td>Ubuntu 22.04/24.04 LTS 或 Debian 12</td>
</tr>
<tr>
<td>续费</td>
<td>优先走活动页同价续费，不按日常价续</td>
</tr>
</tbody>
</table>
<h2>5. 参考资料</h2>
<ul>
<li><a href="https://cloud.tencent.com/product/lighthouse">腾讯云轻量应用服务器</a></li>
<li><a href="https://cloud.tencent.com/document/product/1207/44755">腾讯云轻量实例套餐</a></li>
<li><a href="https://cloud.tencent.com/document/product/1207/50103">腾讯云轻量地域与网络连通性</a></li>
<li><a href="https://www.tencentcloud.com/products/lighthouse">腾讯云国际站 Lighthouse</a></li>
</ul>
]]></content>
    <author><name>卟瓿钚</name></author>
    <category term="私有化部署"/>
  </entry>
  <entry>
    <title>AstrBot 在 Windows 上部署</title>
    <link href="https://blog.0v0.uno/posts/deploy/astrbot-win/" rel="alternate" type="text/html"/>
    <id>https://blog.0v0.uno/posts/deploy/astrbot-win/</id>
    <published>2026-11-11T13:07:27.000Z</published>
    <updated>2026-11-11T13:07:27.000Z</updated>
    <summary>使用 AstrBot Desktop 或 Launcher 在 Windows 上部署.</summary>
    <content type="html"><![CDATA[<h1>使用Astrbot-Desktop部署(推荐)</h1>
<h2>特点</h2>
<p><strong>AstrBot-desktop</strong> 适合在本地电脑快速部署和使用 AstrBot, 支持 ==Windows=={.primary}、==macOS=={.secondary}、==Linux=={.secondary}</p>
<p>但是在 MacOS 和 Linux 中, 个人更推荐使用==源代码部署=={.primary}或者 ==Docker 部署=={.primary}</p>
<h2>下载并安装</h2>
<ol>
<li>打开 <a href="https://github.com/AstrBotDevs/AstrBot-desktop">AstrBot-desktop Releases</a></li>
<li>下载与你系统对应的安装包(如 .exe、.dmg、.rpm、.deb).</li>
<li>安装完成后启动桌面客户端,按向导完成初始化.</li>
</ol>
<h2>常见问题</h2>
<p>::: collapse accordion</p>
<ul>
<li>
<p>是否需要python等环境</p>
<p>不需要, Desktop下载的安装包中会自带Python环境, 所有的内容都是已经打包好的</p>
</li>
<li>
<p>是否需要初始密码</p>
<p>不需要, Desktop==初次启动时=={.primary}, 初始密码输入自动是跳过的</p>
<p>如果是docker或者源代码部署, 在终端中可以查看到初始默认密码</p>
<pre><code>    [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.
</code></pre>
<p>如果出现了需要输入密码的情况, 请这样做:</p>
<ol>
<li>停止 <code>AstrBot</code></li>
<li>删除 <code>AstrBot</code> 的 <code>data</code> 目录下的 <code>dist</code> 文件夹,即 <code>AstrBot/data/dist</code></li>
<li>重新启动 <code>AstrBot</code></li>
</ol>
</li>
<li>
<p>通过 AstrBot 桌面客户端安装的 AstrBot,data 目录在哪？</p>
<p>在家目录下的 <code>.astrbot</code> 目录下.</p>
<p>:::tabs</p>
<p>@tab Windows</p>
<pre><code>  C:\Users\你的用户名\.astrbot
</code></pre>
<p>@tab Linux</p>
<pre><code>  /home/你的用户名/.astrbot
</code></pre>
<p>@tab MacOS</p>
<pre><code>  /Users/你的用户名/.astrbot
</code></pre>
<p>:::</p>
</li>
</ul>
<p>:::</p>
<h1>使用Astrbot-Launcher部署(不推荐)</h1>
<h2>特点</h2>
<p>AstrBot 一键启动器支持 Windows、MacOS、Linux 等多端部署</p>
<h2>安装选择</h2>
<p>对于==操作系统=={.primary}, 有Windows, Linux, MacOS三种操作系统. 对于==CPU=={.primary}, 有x64, ARM64和其他种类</p>
<p>一共有很多种组合, 请按照需求下载</p>
<p>前往<a href="https://github.com/AstrBotDevs/astrbot-launcher">下载页面</a>下载对应版本</p>
<p>:::tabs</p>
<p>@tab Windows</p>
<ul>
<li>Windows x64:下载 EXE 安装包 AstrBot.Launcher_{版本}_x64-setup.exe</li>
<li>Windows ARM64:下载 EXE 安装包 AstrBot.Launcher_{版本}_arm64-setup.exe</li>
</ul>
<p>@tab Linux</p>
<ul>
<li>Debian / Ubuntu(x64):下载 DEB 包 AstrBot.Launcher_{版本}_amd64.deb</li>
<li>Fedora / openSUSE / RHEL / CentOS(x64):下载 RPM 包 AstrBot.Launcher-{版本}-1.x86_64.rpm</li>
<li>其他 Linux 发行版(x64,通用):下载 AppImage AstrBot.Launcher_{版本}_amd64.AppImage</li>
<li>Debian / Ubuntu(ARM64):下载 DEB 包 AstrBot.Launcher_{版本}_arm64.deb</li>
<li>Fedora / openSUSE / RHEL / CentOS(ARM64):下载 RPM 包 AstrBot.Launcher-{版本}-1.aarch64.rpm</li>
<li>其他 Linux 发行版(ARM64,通用):下载 AppImage AstrBot.Launcher_{版本}_aarch64.AppImage</li>
</ul>
<p>@tab MacOS</p>
<ul>
<li>macOS Intel (x64):下载 DMG 安装包 AstrBot.Launcher_{版本}_x64.dmg</li>
<li>macOS Apple Silicon (ARM64):下载 DMG 安装包 AstrBot.Launcher_{版本}_aarch64.dmg</li>
</ul>
<p>:::</p>
]]></content>
    <author><name>卟瓿钚</name></author>
    <category term="私有化部署"/>
  </entry>
  <entry>
    <title>Markdown 缩略词</title>
    <link href="https://blog.0v0.uno/posts/markdown-guide/abbreviations/" rel="alternate" type="text/html"/>
    <id>https://blog.0v0.uno/posts/markdown-guide/abbreviations/</id>
    <published>2026-11-06T00:00:00.000Z</published>
    <updated>2026-11-06T00:00:00.000Z</updated>
    <summary>只定义一次常见缩写，让全称在正文里随时可查。</summary>
    <content type="html"><![CDATA[<p>缩略词让技术写作保持紧凑，同时为需要的读者保留完整术语。定义过的术语会渲染为原生 <code>abbr</code> 元素，悬浮时和辅助技术都能读到全称。</p>
<h2>写法与效果</h2>
<p>在文章任意位置（通常放文末）用 <code>*[术语]: 全称</code> 定义，正文里出现的对应术语会自动获得悬浮释义。</p>
<p><strong>写法</strong></p>
<pre><code>*[SSR]: Server-Side Rendering
*[LCP]: Largest Contentful Paint
*[CLS]: Cumulative Layout Shift

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

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

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

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

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

- :+ 安装依赖

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

  ```powershell
  pnpm.cmd install
  ```

- 校验命令

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

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

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

- 标题能包含 Markdown 吗？

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

- 窄屏下会怎样？

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

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

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

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

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

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

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

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

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

&lt;button class="m3-btn"&gt;{label}&lt;/button&gt;
</code></pre>
<pre><code>.m3-btn
  background: var(--primary)
  color: var(--on-primary)
  border-radius: var(--shape-corner-m)
</code></pre>
<pre><code>{
  "name": "button-demo",
  "version": "1.0.0"
}
</code></pre>
<p>:::</p>
<h4>配置与标记</h4>
<ul>
<li><code>title="字符串"</code>：设置代码树的标题与无障碍标签。</li>
<li><code>height="字符串"</code>：设置桌面视图高度（默认 <code>420px</code>，如 <code>380px</code>、<code>26rem</code>）。</li>
<li><code>entry="文件路径"</code>：指定首次加载时激活的文件。</li>
<li><code>icon="colored" | "simple"</code>：在彩色或极简单色文件图标间切换。</li>
<li><code>:active</code>：在任意围栏代码块上标 <code>:active</code>，指定其为默认激活标签页。</li>
</ul>
<hr />
<h3>2. 本地目录自动引入（<code>@[code-tree]</code>）</h3>
<p>直接指向工作区内任意本地目录路径，构建期自动扫描并生成交互式代码树，无需手动复制文件内容。</p>
<pre><code>@[code-tree title="番剧工具函数" entry="status.ts"](/src/utils/anime)
</code></pre>
<p>@<a href="/src/config">code-tree title="站点配置" entry="siteConfig.ts"</a></p>
]]></content>
    <author><name>卟瓿钚</name></author>
    <category term="Shirone操作指南"/>
  </entry>
  <entry>
    <title>Expressive Code 代码块</title>
    <link href="https://blog.0v0.uno/posts/markdown-guide/expressive-code/" rel="alternate" type="text/html"/>
    <id>https://blog.0v0.uno/posts/markdown-guide/expressive-code/</id>
    <published>2026-11-06T00:00:00.000Z</published>
    <updated>2026-11-06T00:00:00.000Z</updated>
    <summary>Markdown 中使用 Expressive Code 的代码块效果一览。</summary>
    <content type="html"><![CDATA[<p>本文展示基于 <a href="https://expressive-code.com/">Expressive Code</a> 的代码块效果。示例参考官方文档，可查阅其了解更多细节。</p>
<h2>语法高亮</h2>
<p><a href="https://expressive-code.com/key-features/syntax-highlighting/">语法高亮</a></p>
<h3>常规高亮</h3>
<pre><code>console.log('这段代码会被语法高亮')
</code></pre>
<h3>渲染 ANSI 转义序列</h3>
<pre><code>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
</code></pre>
<h2>编辑器与终端框架</h2>
<p><a href="https://expressive-code.com/key-features/frames/">编辑器与终端框架</a></p>
<h3>代码编辑器框架</h3>
<pre><code>console.log('标题属性示例')
</code></pre>
<hr />
<pre><code>&lt;!-- src/content/index.html --&gt;
&lt;div&gt;文件名注释示例&lt;/div&gt;
</code></pre>
<h3>终端框架</h3>
<pre><code>echo "这个终端框架没有标题"
</code></pre>
<hr />
<pre><code>Write-Output "这个有标题！"
</code></pre>
<h3>覆盖框架类型</h3>
<pre><code>echo "看，没有外框！"
</code></pre>
<hr />
<pre><code># 不覆盖的话，这本该是终端框架
function Watch-Tail { Get-Content -Tail 20 -Wait $args }
New-Alias tail Watch-Tail
</code></pre>
<h2>文本与行标记</h2>
<p><a href="https://expressive-code.com/key-features/text-markers/">文本与行标记</a></p>
<h3>标记整行与行范围</h3>
<pre><code>// 第 1 行 - 按行号标记
// 第 2 行
// 第 3 行
// 第 4 行 - 按行号标记
// 第 5 行
// 第 6 行
// 第 7 行 - 按范围 "7-8" 标记
// 第 8 行 - 按范围 "7-8" 标记
</code></pre>
<h3>选择行标记类型（mark、ins、del）</h3>
<pre><code>function demo() {
  console.log('这行被标记为删除')
  // 本行和下一行被标记为新增
  console.log('这是第二行新增')

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

  value={value}
  className={buttonClassName}

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

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

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

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

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

::: field tex
@type object
@optional

TeX 解析器配置项。
:::

::: field output
@type `'svg' | 'chtml'`
@default `'svg'`
@optional

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

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

::: field title
@type string
@required

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

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

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

::: field locale
@type `'en' | 'zh-CN' | 'ja-JP'`
@default `'en'`
@optional

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

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

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

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

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

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

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

::: field legacyMode
@type boolean
@deprecated

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

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

控制结果的格式化方式。
:::
</code></pre>
<p><strong>渲染效果</strong></p>
<p>::: field format
@type <code>'short' | 'long'</code>
@default <code>'short'</code>
@optional</p>
<p>控制结果的格式化方式。
:::</p>
<h2>元数据标签速查</h2>
<table>
<thead>
<tr>
<th>标签</th>
<th>作用</th>
<th>渲染表现</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>@type</code></td>
<td>数据类型</td>
<td>代码令牌</td>
</tr>
<tr>
<td><code>@default</code></td>
<td>默认取值</td>
<td>代码令牌</td>
</tr>
<tr>
<td><code>@required</code></td>
<td>必填</td>
<td>状态徽标</td>
</tr>
<tr>
<td><code>@optional</code></td>
<td>可选</td>
<td>状态徽标</td>
</tr>
<tr>
<td><code>@deprecated</code></td>
<td>废弃</td>
<td>状态徽标</td>
</tr>
</tbody>
</table>
<ul>
<li>元数据之后的任何普通 Markdown 都会成为字段描述。</li>
<li>未知的 <code>@标签</code> 会作为描述文本保留，而不是被丢弃。</li>
</ul>
]]></content>
    <author><name>卟瓿钚</name></author>
    <category term="Shirone操作指南"/>
  </entry>
  <entry>
    <title>Frontmatter 元数据字段说明</title>
    <link href="https://blog.0v0.uno/posts/markdown-guide/frontmatter/" rel="alternate" type="text/html"/>
    <id>https://blog.0v0.uno/posts/markdown-guide/frontmatter/</id>
    <published>2026-11-06T00:00:00.000Z</published>
    <updated>2026-11-06T00:00:00.000Z</updated>
    <summary>Shirone 文章 Frontmatter 全部字段的含义、写法与行为说明。</summary>
    <content type="html"><![CDATA[<p>每篇文章开头用三条横线 <code>---</code> 包裹一段 YAML，称为 <strong>Frontmatter</strong>，用来声明文章的标题、日期、分类、行为等元数据。</p>
<h2>完整字段模板</h2>
<pre><code>---
# ── 必填 ──────────────────────────────
title: "文章标题"                    # 文章主标题
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: "文章摘要，用于卡片和 SEO"   # 留空自动截取正文前段
image: "./image.png"                # 封面图（相对路径或外链）

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

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

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

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

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

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



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

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

@tab npm

```powershell
npm run dev
```

@tab pnpm

```powershell
pnpm.cmd dev
```

@tab Bun#bun

```powershell
bun run dev
```

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

@tab 本地工作站

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

@tab 托管预览环境

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

@tab 持续集成

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

@tab 生产部署

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

@tab 离线恢复流程

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

:::
</code></pre>
<p><strong>渲染效果</strong></p>
<p>::: tabs</p>
<p>@tab 本地工作站</p>
<p>开发功能时使用本地工具链。</p>
<p>@tab 托管预览环境</p>
<p>发布一个临时预览用于评审。</p>
<p>@tab 持续集成</p>
<p>对每次变更运行确定性校验。</p>
<p>@tab 生产部署</p>
<p>把验证过的产物发布到生产。</p>
<p>@tab 离线恢复流程</p>
<p>网络不可用时从本地产物恢复。</p>
<p>:::</p>
<h2>规则</h2>
<p>每个组至少需要两个 <code>@tab</code> 分节，且每个分节的正文需与标记之间空一行。非法或不完整的组保留为普通可读 Markdown。</p>
]]></content>
    <author><name>卟瓿钚</name></author>
    <category term="Shirone操作指南"/>
  </entry>
  <entry>
    <title>Markdown 剧透黑幕</title>
    <link href="https://blog.0v0.uno/posts/markdown-guide/spoilers/" rel="alternate" type="text/html"/>
    <id>https://blog.0v0.uno/posts/markdown-guide/spoilers/</id>
    <published>2026-11-06T00:00:00.000Z</published>
    <updated>2026-11-06T00:00:00.000Z</updated>
    <summary>隐藏行内答案，同时让剧透内容保持无障碍可访问。</summary>
    <content type="html"><![CDATA[<p>剧透黑幕把简短答案或情节细节遮住，但不从文档中移除。悬浮、聚焦或激活该原生控件即可显现内容。</p>
<h2>基础用法</h2>
<p><strong>写法</strong></p>
<pre><code>答案是 :spoiler[**42**]，这句话其余部分仍是普通 Markdown。
</code></pre>
<p><strong>渲染效果</strong></p>
<p>答案是 :spoiler[<strong>42</strong>]，这句话其余部分仍是普通 Markdown。</p>
<h2>含行内代码与较长内容</h2>
<p><strong>写法</strong></p>
<pre><code>剧透内可包含 `行内代码`，也可以写 :spoiler[一段带**强调**的较长细节]。
</code></pre>
<p><strong>渲染效果</strong></p>
<p>剧透内可包含 <code>行内代码</code>，也可以写 :spoiler[一段带<strong>强调</strong>的较长细节]。</p>
<h2>说明</h2>
<p>生成的 HTML 使用带 <code>aria-expanded</code> 状态的原生按钮。没有 JavaScript 时，悬浮和聚焦仍能显现文字；可选的运行时会额外提供点击与键盘切换。</p>
]]></content>
    <author><name>卟瓿钚</name></author>
    <category term="Shirone操作指南"/>
  </entry>
  <entry>
    <title>Markdown 步骤条</title>
    <link href="https://blog.0v0.uno/posts/markdown-guide/steps/" rel="alternate" type="text/html"/>
    <id>https://blog.0v0.uno/posts/markdown-guide/steps/</id>
    <published>2026-11-06T00:00:00.000Z</published>
    <updated>2026-11-06T00:00:00.000Z</updated>
    <summary>把有先后顺序的操作流程呈现为紧凑、无障碍的步骤流。</summary>
    <content type="html"><![CDATA[<p>步骤条用于顺序很重要的操作流程。组件不打断文章阅读流：一条安静的序号导轨提供方向感，而标题、段落、链接、列表和代码仍保留各自的原生 Markdown 角色。</p>
<h2>有序列表语法</h2>
<p>把一个 Markdown 有序列表包进 <code>:::steps</code> 容器，每个顶层列表项成为一步。</p>
<pre><code>:::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
   ```
:::
</code></pre>
<p>:::steps[生产环境部署]</p>
<ol>
<li>
<p><strong>克隆并准备工作区</strong></p>
<p>克隆仓库并进入项目目录。</p>
<pre><code>git clone https://github.com/LyraVoid/Shirone.git
Set-Location Shirone
</code></pre>
</li>
<li>
<p><strong>安装依赖</strong></p>
<p>使用仓库锁定的包管理器。</p>
<pre><code>pnpm.cmd install
</code></pre>
</li>
<li>
<p><strong>运行项目检查</strong></p>
<p>确认 Astro 诊断与 TypeScript 检查通过。</p>
<pre><code>npx.cmd astro check
pnpm.cmd type-check
</code></pre>
</li>
<li>
<p><strong>构建生产站点</strong></p>
<p>生成静态站点与搜索索引。</p>
<pre><code>pnpm.cmd build
</code></pre>
</li>
</ol>
<p>:::</p>
<h2>选项</h2>
<ul>
<li><code>:::steps[标题]</code> 或 <code>title="标题"</code> 添加可见标签与无障碍名称。</li>
<li><code>start=4</code> 修改首个显示步骤的序号。</li>
<li>容器内必须恰好只有一个有序列表。非法或混合输入保留为普通可读 Markdown，不做启发式解释。</li>
<li>渲染在站点构建期完成，不增加客户端 JavaScript 或网络请求。</li>
</ul>
]]></content>
    <author><name>卟瓿钚</name></author>
    <category term="Shirone操作指南"/>
  </entry>
  <entry>
    <title>在文章中嵌入视频</title>
    <link href="https://blog.0v0.uno/posts/markdown-guide/video/" rel="alternate" type="text/html"/>
    <id>https://blog.0v0.uno/posts/markdown-guide/video/</id>
    <published>2026-11-06T00:00:00.000Z</published>
    <updated>2026-11-06T00:00:00.000Z</updated>
    <summary>演示如何在博客文章中嵌入各平台视频。</summary>
    <content type="html"><![CDATA[<p>除了直接粘贴平台 iframe 嵌入代码，Shirone 还提供各平台的专用指令，均为 SSR facade：初始只渲染封面占位，接近视口或点击时才加载真实播放器。</p>
<pre><code>---
title: 在文章中嵌入视频
published: 2023-10-19
---
</code></pre>
<h2>YouTube</h2>
<p>::youtube{id="5gIf0_xpFPI" title="YouTube 视频" preload="auto"}</p>
<pre><code>::youtube{id="5gIf0_xpFPI" title="YouTube 视频" preload="auto"}
</code></pre>
<h2>Bilibili</h2>
<p>::bilibili{bvid="BV1fK4y1s7Qf" title="Bilibili 视频" p=1 preload="auto"}</p>
<pre><code>::bilibili{bvid="BV1fK4y1s7Qf" title="Bilibili 视频" p=1 preload="auto"}
</code></pre>
<h2>AcFun</h2>
<p>::acfun{acid="ac48649632" title="AcFun 视频" preload="auto"}</p>
<pre><code>::acfun{acid="ac48649632" title="AcFun 视频" preload="auto"}
</code></pre>
<h2>ArtPlayer（自建/直链）</h2>
<p>::artplayer{src="https://www.pexels.com/download/video/38538991/" title="Sintel 预告片" preload="auto"}</p>
<pre><code>::artplayer{src="https://www.pexels.com/download/video/38538991/" title="Sintel 预告片" preload="auto"}
</code></pre>
<p><code>preload="auto"</code> 会在视频接近视口时预加载播放器；默认 <code>none</code> 则需点击才加载。</p>
]]></content>
    <author><name>卟瓿钚</name></author>
    <category term="Shirone操作指南"/>
  </entry>
</feed>
