Skip to content

Serv00

Jump to bottom
Kana edited this page May 17, 2026 · 1 revision

Serv00 部署指南

Serv00 常见环境是 FreeBSD 用户空间。InboxBridge 已尽量减少原生依赖，当前依赖不需要 esbuild、tsx 或 better-sqlite3，更适合在 Serv00 上运行。

推荐配置

TELEGRAM_UPDATE_MODE=polling
AI_DRAFTS_ENABLED=false
DATABASE_URL=file:./data/inboxbridge.sqlite

polling 不需要公网回调地址，是 Serv00 上最省心的方式。

1. 准备 Node.js 与 npm

如果系统提供 node24 / npm24，建议使用对应版本：

node24 -v
npm24 -v

项目要求 Node.js 24+。如果默认 node 不是 24，请在启动脚本里明确使用 node24，或调整 PATH。

2. npm prefix 问题

Serv00 上可能遇到：

npm error config prefix cannot be changed from project config

这通常是因为当前目录或用户目录存在 .npmrc，并且 npm 把它当作项目配置。可在非项目目录设置用户级 prefix：

mkdir -p "$HOME/.npm-global"
cd /tmp
npm24 config set prefix "$HOME/.npm-global" --location=user
npm24 config get prefix --location=user
cd

如果在 $HOME 下查询时仍看到提示，但输出已经是 $HOME/.npm-global，通常说明用户级配置已经生效。实际安装项目依赖时优先在仓库内使用 npm ci，不需要全局安装依赖。

3. 拉取代码

示例目录：

mkdir -p "$HOME/apps"
cd "$HOME/apps"
git clone <你的仓库地址> InboxBridge
cd InboxBridge

如果已经有目录：

cd "$HOME/apps/InboxBridge"
git pull

4. 安装依赖

npm24 ci

如果你用的是默认 npm：

npm ci

当前项目依赖为纯 TypeScript 构建路径，不应再出现 libsql 不支持 FreeBSD 或 esbuild EACCES 这类旧问题。

5. 配置 .env 

cp .env.example .env
nano .env

最小配置示例：

TELEGRAM_BOT_TOKEN=你的_bot_token
TELEGRAM_MANAGEMENT_CHAT_ID=-1001234567890
TELEGRAM_UPDATE_MODE=polling
TELEGRAM_ADMIN_USER_IDS=123456789
DATABASE_URL=file:./data/inboxbridge.sqlite
AI_DRAFTS_ENABLED=false

注意：

  • .env 不能提交到 Git。
  • TELEGRAM_MANAGEMENT_CHAT_ID 要填私密 Forum 管理群 ID，不是用户 ID。
  • TELEGRAM_ADMIN_USER_IDS 要填管理员个人数字 user_id，不是 @username。

6. 检查 Telegram 权限

npm24 run telegram:check

如果输出中 can_manage_topics=false，说明 bot 不是管理员或缺少管理 topics 权限。

需要完整测试时：

TELEGRAM_CHECK_SEND_TEST=true npm24 run telegram:check
TELEGRAM_CHECK_TOPIC_TEST=true npm24 run telegram:check

7. 数据库迁移与构建

npm24 run migrate
npm24 run build

如果迁移提示缺少 TELEGRAM_BOT_TOKEN 或 TELEGRAM_MANAGEMENT_CHAT_ID，说明当前运行进程没有读到 .env，请确认：

  • 命令在仓库根目录执行。
  • .env 文件名正确。
  • 变量名没有多余空格。
  • 值没有被错误引号包裹。

8. 前台启动验证

npm24 run dev

看到类似输出即可开始测试：

Starting InboxBridge.

然后用外部账号私聊 bot，确认管理群自动创建 Topic。

9. 常驻运行

Serv00 的具体进程管理方式可能随账号配置变化。通用原则：

  1. 先运行 npm24 run build。
  2. 常驻命令使用编译产物：
node24 dist/src/app/main.js

如果使用 PM2：

pm2 start dist/src/app/main.js --name inboxbridge --interpreter node24
pm2 save
pm2 logs inboxbridge

如果 PM2 不可用，请使用 Serv00 面板或系统允许的 supervisor/daemon 方式，命令保持为 node24 dist/src/app/main.js。

10. 备份

重点备份：

$HOME/apps/InboxBridge/.env
$HOME/apps/InboxBridge/data/inboxbridge.sqlite

建议升级前先备份 SQLite 文件。

11. Serv00 常见问题

tsc: Permission denied

旧脚本如果直接调用 tsc，可能被 Serv00 权限策略拦住。当前脚本使用：

node ./node_modules/typescript/bin/tsc -p tsconfig.json

如果仍遇到权限问题，请确认代码已更新，并重新 npm24 ci。

createForumTopic: chat not found

通常是：

  • TELEGRAM_MANAGEMENT_CHAT_ID 填错。
  • bot 没有加入管理群。
  • 管理群不是 supergroup。

运行 npm24 run telegram:check 查看真实状态。

not enough rights to create a topic

bot 已在群里，但没有管理 topics 权限。把 bot 提升为管理员，并开启管理 topics 权限。

message thread not found

对应 Topic 被删除或失效。InboxBridge 会在下一次用户来信时清理旧会话并重建 Topic。

Clone this wiki locally