把前端组件移植到网站#

1. 复制组件与配置#

如果目标也是 Astro 项目，先按相同路径复制这四个文件：

1
src/components/widget/Presence.astro
2
src/config/presenceConfig.ts
3
src/types/presenceConfig.ts
4
src/utils/presence-store.ts

Presence.astro 对 presence-store.ts 的引用使用的是 import type，前端只需要其中的 PresenceData 类型，不会因此拥有服务端存储功能。你也可以把这个接口单独移到自己的类型文件，再修改组件顶部和 <script> 内的两处类型导入。

源码中的 @/ 指向 src/。目标项目如果没有这个别名，在原有 tsconfig.json 的 compilerOptions.paths 中合并：

1
{
2
  "@/*": ["./src/*"]
3
}

也可以把组件里的导入改成目标项目对应的相对路径。配置文件与类型文件之间的相对路径需要一起保持正确。

2. 处理卡片外壳与样式#

面板使用了 Firefly 的 WidgetLayout.astro。如果你的网站已经有这个组件，可以直接使用。

如果是其他 Astro 主题，可以换成自己的卡片容器：

在 Presence.astro 中删除这一行：

1
import WidgetLayout from "@/components/common/WidgetLayout.astro";

把包裹 <presence-widget> 的 <WidgetLayout ...> 和 </WidgetLayout> 分别替换为：

1
<section id="presence-widget" class:list={["presence-card", className]} style={style}>
2
  <!-- 原有 presence-widget 及内部内容全部保留 -->
3
</section>

上面展示的是外层替换位置，不要把组件内部内容替换成注释。原有 <script> 和 <style> 也要保留。

随后在组件原有 <style> 中加入卡片样式，补上它使用的 CSS 变量和工具类：

1
.presence-card {
2
  --radius-large: 1rem;
3
  --primary: #2563eb;
4
  --btn-regular-bg: #f1f5f9;
5
  --btn-regular-bg-hover: #e2e8f0;
6
  --line-divider: #e5e7eb;
7
  padding: 1rem;
8
  border: 1px solid var(--line-divider);
9
  border-radius: var(--radius-large);
10
  background: #fff;
11
}
12

13
:global(.dark) .presence-card {
14
  --primary: #93c5fd;
15
  --btn-regular-bg: #262626;
16
  --btn-regular-bg-hover: #404040;
17
  --line-divider: #404040;
18
  background: #171717;
19
}
20

21
.sr-only {
22
  position: absolute;
23
  width: 1px;
24
  height: 1px;
25
  padding: 0;
26
  margin: -1px;
27
  overflow: hidden;
28
  clip: rect(0, 0, 0, 0);
29
  white-space: nowrap;
30
  border: 0;
31
}

原组件的深色样式根据祖先元素上的 .dark 类切换。如果你的主题用 data-theme 等方式控制配色，需要同步调整相关选择器。直接复制 Firefly 的 WidgetLayout.astro 则会继续带入 astro-icon、国际化模块和主题工具类依赖，移植时也要处理它们。

3. 在页面或侧边栏中挂载#

在自己的 Astro 布局或侧边栏组件里导入并渲染：

1
---
2
import Presence from "@/components/widget/Presence.astro";
3
---
4

5
<aside>
6
  <Presence />
7
</aside>

这个组件的交互由内置 <script> 注册自定义元素完成，直接使用 <Presence /> 即可。

如果你使用的是带组件注册表的 Firefly 版本，则在 src/components/layout/SideBar.astro 的 componentMap 中注册 presence: Presence，在 src/types/sidebarConfig.ts 的 WidgetComponentType 中加入 "presence"，再向 src/config/sidebarConfig.ts 对应的侧栏数组添加：

1
{
2
  type: "presence",
3
  enable: true,
4
  position: "sticky",
5
  showOnPostPage: true,
6
}

本文源码已包含注册项，使用这份源码时只需检查是否启用。手机端由 mobileBottomComponents 单独控制；其中没有 position 字段，需要按移动端配置单独添加。

4. 确认读取地址#

组件的 loadPresence() 默认请求：

1
const response = await fetch("/api/presence/", {
2
  cache: "no-store",
3
  signal: this.listeners?.signal,
4
});

这意味着浏览器访问的是网站当前域名下的 API。下面的部署步骤会让 Nginx 把这个路径转发给 Presence 服务。

如果网站托管在其他平台，例如静态托管服务，你仍然需要在网站域名下设置相应的 API 转发，或改成自己的独立 API 地址。现有 Fastify 服务没有配置 CORS，单纯把这里换成另一个域名，并不能保证浏览器成功读取；跨域方案还需要在服务端或代理层配置允许的网站来源。使用 HTTPS 网站时，API 也应使用 HTTPS。

组件使用根路径 /api/presence/。即使网站放在 /blog/ 子目录，它仍请求域名根目录的 API，代理路径需要与之对应。

前端只需要 GET 地址，不要在组件、网页脚本或公开环境变量中填写 Bearer Token。

5. 可选：先在本地预览#

在完整源码仓库中执行：

1
pnpm install --frozen-lockfile
2
pnpm dev

开发模式下，组件会显示 DEV 状态切换按钮，方便预览不同状态的外观，生产构建不会显示这些按钮。源码中的 USE_MOCK_PRESENCE 默认是 false；如需持续使用模拟状态预览，可以临时改为 true，完成后改回 false。保持 false 时，后续真实 API 轮询会覆盖按钮设置的预览状态。

如果要在其他 Astro 项目里使用本地开发 API，还要复制 src/integrations/presence-dev-api.ts，并把下面的集成合并到原有 astro.config.mjs：

1
import presenceDevApi from "./src/integrations/presence-dev-api";
2

3
// 在已有 integrations 数组中追加：
4
presenceDevApi(),

这套开发接口仅保存内存状态，POST 不要求 Token，只用于本地调试。它不会随静态构建变成生产 API，正式上线仍需要下面的独立服务端。

1. 在 Linux 上构建发布目录#

先检查环境：

1
node -v
2
pnpm -v
3
nginx -v

使用一个专门的源码构建目录：

1
mkdir -p "$HOME/presence-build"
2
cd "$HOME/presence-build"
3
git clone <源码仓库地址> Firefly
4
cd Firefly
5

6
pnpm install --frozen-lockfile
7
pnpm presence:server:build
8
pnpm --filter @nightbug/presence --prod deploy ./release-presence
9

10
ls -l release-presence/dist/index.js

release-presence 在首次部署时应是一个尚未使用的输出目录。再次构建时可以换一个新目录名，避免与已有产物混在一起。

pnpm deploy 会带上生产依赖。不要直接把 Windows 项目中的 node_modules 复制到 Linux；网站的静态构建产物和这个 API 发布目录也需要分别部署。

2. 创建运行用户并安装程序#

仍在 Linux 的源码根目录执行：

1
sudo useradd --system --user-group --home-dir /var/lib/nightbug-presence \
2
  --no-create-home --shell /usr/sbin/nologin presence
3

4
sudo install -d -o root -g root -m 755 /opt/nightbug-presence
5
sudo cp -a release-presence/. /opt/nightbug-presence/
6
sudo chown -R root:root /opt/nightbug-presence
7
sudo chmod -R a+rX /opt/nightbug-presence
8

9
sudo install -d -o presence -g presence -m 750 /var/lib/nightbug-presence

这是首次安装流程。如果 presence 用户已经存在，不需要重复创建。程序文件放在 /opt/nightbug-presence，状态文件放在 /var/lib/nightbug-presence；后者必须允许 presence 用户写入。

3. 设置服务端 Token#

生成一份随机密钥：

1
openssl rand -hex 32

妥善保存输出，稍后在 Windows 客户端中输入同一份值。

从仓库安装环境变量模板：

1
sudo install -o root -g root -m 600 \
2
  deploy/presence/nightbug-presence.env.example /etc/nightbug-presence.env
3
sudoedit /etc/nightbug-presence.env

修改为：

1
PRESENCE_TOKEN=替换为刚生成的随机密钥
2
PRESENCE_HOST=127.0.0.1
3
PRESENCE_PORT=8765
4
PRESENCE_STATE_FILE=/var/lib/nightbug-presence/presence.json

这里的 Token 是服务端用于验证 Agent 的秘密。不要把真实值提交到仓库，也不要发给访客。

4. 配置 systemd 并启动#

安装仓库中的服务模板：

1
sudo install -o root -g root -m 644 \
2
  deploy/presence/nightbug-presence.service \
3
  /etc/systemd/system/nightbug-presence.service
4
command -v node

模板默认使用：

1
User=presence
2
Group=presence
3
WorkingDirectory=/opt/nightbug-presence
4
EnvironmentFile=/etc/nightbug-presence.env
5
ExecStart=/usr/bin/node /opt/nightbug-presence/dist/index.js

如果 Node.js 实际位于其他位置，使用 sudoedit /etc/systemd/system/nightbug-presence.service 修改 ExecStart。路径必须让 presence 用户可执行；模板开启了 ProtectHome=true，因此不要直接指向个人 home 目录里的 Node.js。

启动并检查：

1
sudo systemctl daemon-reload
2
sudo systemctl enable --now nightbug-presence
3
sudo systemctl status nightbug-presence --no-pager
4
curl -i http://127.0.0.1:8765/api/presence/

首次启动、尚无上报时，GET 应返回 200，内容类似：

1
{
2
  "state": "offline",
3
  "title": "当前离线",
4
  "detail": "下次见",
5
  "updatedAt": 0
6
}

服务读取到已有的合法状态文件时，会恢复此前保存的数据。GET 不会自动把过期状态改成离线，这是前端负责的判断。

5. 用 Nginx 对外提供 HTTPS API#

在网站域名对应、监听 HTTPS 的 server 块内部加入下面的配置，或把它保存到该站点已经 include 的扩展配置文件里：

1
location ~ ^/api/presence(?:/|/update/?)?$ {
2
    proxy_pass http://127.0.0.1:8765;
3
    proxy_http_version 1.1;
4
    proxy_set_header Host $host;
5
    proxy_set_header X-Real-IP $remote_addr;
6
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
7
    proxy_set_header X-Forwarded-Proto $scheme;
8

9
    client_max_body_size 16k;
10
    add_header Cache-Control "no-store" always;
11
}

这里的 proxy_pass 保留原请求路径。配置应覆盖 /api/presence/ 和 /api/presence/update/，并且不能被站点已有的更高优先级规则截走。

使用宝塔面板时，可以通过站点配置编辑对应的 vhost，或使用它已 include 的站点扩展目录。不要把这段 location 放到 Nginx 顶层，也不要覆盖整份网站配置。

检查语法后重载：

1
sudo nginx -t
2
sudo systemctl reload nginx
3
curl -i https://example.com/api/presence/

宝塔等环境如果由面板管理 Nginx，应使用面板对应的检查与重载方式。公网 GET 应返回与本机接口一致的 JSON，并包含 Cache-Control: no-store。如果前面还有 CDN，也要让这两个 API 路径跳过缓存。

API 只监听 127.0.0.1:8765，不需要向公网开放 8765 端口。公网请求通过已有的 HTTPS 入口进入。

6. 验证上报与鉴权#

先测试未携带 Token 的请求：

1
curl -i https://example.com/api/presence/update/ \
2
  -H 'Content-Type: application/json' \
3
  --data '{"state":"coding","title":"正在写代码"}'

应返回 401 Unauthorized。

再测试正确 Token。下面使用隐藏输入和标准输入传递密钥，避免把真实值直接写进命令历史或 curl 的参数：

1
read -rsp 'Presence Token: ' presence_token
2
printf '\n'
3
printf 'header = "Authorization: Bearer %s"\n' "$presence_token" | \
4
  curl --config - -i https://example.com/api/presence/update/ \
5
    -H 'Content-Type: application/json' \
6
    --data '{"state":"coding","title":"正在写代码","app":"Visual Studio Code","detail":"部署测试"}'
7
unset presence_token

应返回 200。再次 GET，确认 state、title、app 等字段已经变化，并且包含数值形式的 since、updatedAt。

重复发送相同 state 后，since 应保持不变，updatedAt 则继续刷新。至此，API 已经具备接收客户端上报的条件。

1. 构建客户端#

在 Windows x64 构建电脑的完整源码根目录执行：

1
node -v
2
pnpm -v
3
dotnet --list-sdks
4

5
pnpm install --frozen-lockfile
6
pnpm presence:agent:exe

确认已安装 .NET 8 SDK。成功后，发布目录是：

1
release/presence-agent/
2
├── NightbugPresence.exe
3
├── NightbugPresenceTray.exe
4
├── config.example.json
5
└── README.md

如果已经拿到与你所用配置对应的发布版，可以跳过构建。两个 EXE 要一起保留：Tray 负责托盘和交互，另一个负责检测与上报。

2. 放入固定目录并设置 Token#

将发布目录中的文件放到普通用户可写的位置，例如：

1
D:\Apps\NightbugPresence\

进入该目录并设置 Token：

1
Set-Location D:\Apps\NightbugPresence
2
.\NightbugPresence.exe --set-token

输入服务端 /etc/nightbug-presence.env 中的那份 Token。程序会通过 Windows DPAPI 的 CurrentUser 范围加密，保存为同目录的 token.dat。

这个命令也会读取或生成普通配置。不要把 Token 写进 config.json，也不要直接把 token.dat 当成可以跨机器、跨账户复用的凭据；更换 Windows 账户或电脑后，应重新设置 Token。

3. 编辑客户端配置#

在 EXE 同级的 config.json 中填写：

1
{
2
  "apiUrl": "https://example.com/api/presence/update/",
3
  "detectInterval": 5000,
4
  "heartbeatInterval": 30000,
5
  "idleTimeout": 600000
6
}

配置中的所有时间单位都是毫秒。这里填写的是上报地址，不能填成前端使用的 GET 地址。

普通配置优先级为“合法的环境变量 → config.json → 内置默认值”。对应环境变量是 PRESENCE_API_URL、PRESENCE_DETECT_INTERVAL、PRESENCE_HEARTBEAT_INTERVAL、PRESENCE_IDLE_TIMEOUT。Token 则优先读取 PRESENCE_TOKEN，没有配置时再读取 token.dat。

如果曾经设置过这些环境变量，修改 JSON 后仍可能被覆盖。执行下面的命令检查最终值及其来源：

1
.\NightbugPresence.exe --show-config

确认 API 是自己的 HTTPS 地址，Token 显示为已配置。修改配置或 Token 后，需要重新启动 Agent，让 Worker 重新读取。

4. 启动托盘与登录自启#

双击 NightbugPresenceTray.exe，也可以通过 PowerShell 启动：

1
Start-Process -FilePath .\NightbugPresenceTray.exe -WindowStyle Hidden

Tray 会启动后台 Worker。右键托盘图标可以查看状态、立即同步、暂停或恢复上报，也可以重新启动 Agent。

需要登录 Windows 后自动运行时，执行：

1
.\NightbugPresence.exe --enable-autostart
2
.\NightbugPresence.exe --autostart-status

这是当前用户的登录自启动。以后移动安装目录，应先禁用旧路径，再从新目录启用一次：

1
.\NightbugPresence.exe --disable-autostart

日常入口是 Tray。只启动其中一个后台 EXE，无法得到完整的托盘交互体验。

修改状态显示内容#

例如，把已有的 coding 改成自己的文案：

1
coding: {
2
  icon: "💻",
3
  title: "正在写代码",
4
  app: "Visual Studio Code",
5
  detail: "今天也在修 Bug",
6
  status: "Online",
7
  availability: "online",
8
},

title、app、detail 是 Agent 上报时使用的默认内容，进程规则还可以覆盖这些值；前端显示真实 API 返回的正文。icon、illustration、status 和 availability 则用于前端表现。只修改网站上的默认正文，不会覆盖旧 Agent 继续上报的文案。

添加或修改进程映射#

在 processRules 中，为已有状态增加程序：

1
{
2
  state: "coding",
3
  processes: [
4
    { process: "Code.exe", app: "Visual Studio Code" },
5
    { process: "Cursor.exe", app: "Cursor" },
6
  ],
7
},

通过 Windows 任务管理器的“详细信息”确认实际进程名。这里匹配的是前台程序的可执行文件名，忽略大小写，但需要精确匹配；规则从上往下检查，首次命中即停止。示例程序名仍应以你电脑上的实际值为准。

例如，将 java.exe 映射为 Minecraft，会把其他使用同名 Java 进程的前台程序也归到这个状态。规则只能反映进程级信息，需要根据自己的使用习惯取舍。

现有源码把聊天状态写成 chating。使用时保持这个 key 一致；如果要改为其他拼写，需要同步修改 states 和对应的 processRules。

新增一种状态#

先在 states 中增加配置，再在 processRules 中引用同一个 key：

1
// 添加到 states：
2
drawing: {
3
  icon: "🎨",
4
  title: "正在画画",
5
  detail: "慢慢涂两笔",
6
  status: "Online",
7
  availability: "online",
8
},
9

10
// 添加到 processRules 数组：
11
{
12
  state: "drawing",
13
  processes: [
14
    { process: "Photoshop.exe", app: "Adobe Photoshop" },
15
  ],
16
},

这两段是添加到不同位置的配置片段，不要合并成一个对象。普通状态的 TypeScript 类型和开发接口状态列表会从 states 自动派生。

生产 API 目前按字符格式校验状态 key，允许字母、数字、下划线和连字符，长度最多 64；它不使用固定状态白名单。因此新增合法 key 通常无需修改服务端，但前端必须先具备对应展示配置，否则读取新状态时可能无法渲染。新增状态可以先发布网站，再更新 Agent。

使用自己的插画#

例如把图片放到：

1
public/assets/presence/coding.webp

在 ui 中打开插画，并在相应状态配置中填写路径：

1
// ui 中：
2
useIllustration: true,
3

4
// coding 中：
5
illustration: "/assets/presence/coding.webp",

文件路径里的 public 不会出现在访问 URL 中。原组件在没有插画或图片加载失败时会回退为 emoji。

修改后需要重新构建什么#

更新 Agent 前先退出 Tray，保留已有的 config.json 和 token.dat，替换两个 EXE 后再启动。已经存在的 config.json 会优先于新的内置默认值；想修改现有安装的检测间隔，应直接修改 JSON。

前端的 offlineTimeout 应明显大于 Agent 的 heartbeatInterval。默认 90 秒对 30 秒留出了网络波动空间；如果把心跳改为 60 秒，也要相应增加离线阈值。