跳到內容
TomoriBot

手動設定

這是給偏好不用引導式精靈的技術背景使用者的手動安裝流程。如果你想要有人一步步帶著走，請改用設定精靈，它會建立.env、產生安全的CRYPTO_SECRET、設定PostgreSQL，並幫你跑完安裝。

事前需求

Section titled “事前需求”
  • Bun
  • 原生安裝的PostgreSQL，或跑在Docker容器裡（請看步驟2）

PostgreSQL結構描述、pgcrypto、種子資料與移轉會在bot啟動時自動初始化。

1. 安裝

Section titled “1. 安裝”
Terminal window
git clone https://github.com/Bredrumb/TomoriBot.git
cd TomoriBot
bun install --frozen-lockfile

2. 設定

Section titled “2. 設定”

根據範例建立環境文件並填寫所需的值：

Terminal window
cp .env.example .env

必需的：

  • DISCORD_TOKEN：你的Discord機器人令牌（啟用GuildMembers、MessageContent和GuildPresences特權意圖）。
  • CRYPTO_SECRET：32個字元的加密金鑰（用於加密儲存的API金鑰）。
  • PostgreSQL連接：POSTGRES_HOST、POSTGRES_PORT、POSTGRES_USER、POSTGRES_PASSWORD、POSTGRES_DB。

請將加密金鑰的受保護複本與資料庫備份分開儲存。新的備份不包含 .env。對於金鑰輪換，請使用 CRYPTO_SECRET_V1、CRYPTO_SECRET_V2 或任何後續的正整數版本，並可選擇使用 CRYPTO_SECRET_CURRENT。

.env.optional.example中有選購的調音功能。複製你想要自訂的任何值（限制、逾時、功能切換、本機伺服器URL等）。

自訂表達式預設上傳到data/custom-expressions/下的本機檔案。將該目錄保留在持久性儲存中。EXPRESSION_STORAGE_BACKEND接受local、gcs或s3。雲端後端需要EXPRESSION_STORAGE_BUCKET和對應的SDK憑證。S3也使用AWS_REGION（預設us-east-1）和選購S3_ENDPOINT。GCS使用應用程式預設憑證。表達式使用自己的儲存桶設定；頭像儲存設定未選擇表情桶。物件仍然可以透過SDK讀取，並以位元組形式附加，因此不需要公開提供的媒體URL。恢復現有參考時保留後端、儲存桶和物件鍵。

MAX_CUSTOM_EXPRESSIONS_PER_SERVER 限制每個伺服器的自訂表情數量（預設 20，最小 1）。連結與上傳的檔案在所有預設之間共用該限制；原生表情符號與貼圖不計入。變更後請重啟機器人。調低限制會保留現有表情並允許編輯與刪除，但會阻止新增，直到數量低於限制為止。

3. 執行

Section titled “3. 執行”
Terminal window
bun run dev

當你看到TomoriBot up and running!，就到Discord並在你的伺服器執行/setup，連接一個AI供應商並初始化bot。這個指令會開啟一個引導式檢查清單面板，而且在你按下完成設定之前不會寫入任何東西；步驟請看快速開始。

如果你想讓選用的本機伺服器（SearXNG、Crawl4AI、本機TTS/STT）跟著bot一起啟動，請用bun run launch取代bun run dev：

Terminal window
bun run launch --searxng --crawl4ai
bun run launch --help        # see all flags

選用額外項目（手動的「完整安裝」）

Section titled “選用額外項目（手動的「完整安裝」）”

設定精靈的完整安裝路徑會在基礎安裝之上疊加四個輕量的額外項目。它們都不是執行bot的必要條件，但每一項都會解鎖一個功能。如果你是手動安裝，想要哪一項就加哪一項：

pgvector：文件與RAG記憶

Section titled “pgvector：文件與RAG記憶”

RAG（文件上傳與跨頻道回想）會把嵌入向量存在vector欄位，這需要 pgvector 擴充功能。請依你的PostgreSQL主版本安裝：

Terminal window
# Debian/Ubuntu, e.g. for PostgreSQL 16
sudo apt-get install -y postgresql-16-pgvector

接著在你的資料庫上啟用一次。用.env裡的POSTGRES_*值透過psql連線，它會提示你輸入POSTGRES_PASSWORD：

Terminal window
# Native / host psql (substitute your own POSTGRES_USER and POSTGRES_DB):
psql -h localhost -p 5432 -U tomori -d tomodb


# Or, if the database runs in the Docker container from step 2:
docker exec -it tomori-db psql -U tomori -d tomori

連線之後，執行：

CREATE EXTENSION vector;

沒有pgvector，bot仍然可以執行，但RAG功能會完全無法使用。還原備份之前，目標資料庫也必須先有這個擴充功能；詳情請看 維護與備份。

pg_cron：排程清理工作

Section titled “pg_cron：排程清理工作”

pg_cron提供選用的定期資料庫維護（冷卻與提醒資料列的清理）。本repo的Docker Compose已經設定好它。

如果是你自己管理的PostgreSQL，請找出目前生效的設定檔：

SHOW config_file;

在postgresql.conf啟用擴充功能。如果shared_preload_libraries已經列出其他函式庫，就附加在後面：

shared_preload_libraries = 'pg_cron'   # e.g. 'pg_stat_statements,pg_cron'
cron.database_name = 'your_dbname'

重新啟動PostgreSQL，然後：

CREATE EXTENSION IF NOT EXISTS pg_cron;

Tokenizer 資產

Section titled “Tokenizer 資產”

NovelAI 文字生成與依模型調整的 logit 偏權值需要本機的 tokenizer 資產：

Terminal window
bun run setup:tokenizers

如果 Hugging Face 存取失敗，請先設定存取權杖：

Terminal window
# PowerShell
$env:HF_TOKEN="hf_xxx"; bun run setup:tokenizers


# Linux / macOS
HF_TOKEN=hf_xxx bun run setup:tokenizers

缺少資產會停用選用的 logit 偏權值。NovelAI 文字生成需要其三個 tokenizer 家族，如果缺少或無效則會傳回設定錯誤。這些家族使用固定的公開 MIT 定義，不需要 Hugging Face 權杖。若要僅安裝這些家族：

Terminal window
bun run setup:tokenizers --family novelai_nerdstash_v2
bun run setup:tokenizers --family novelai_llama3
bun run setup:tokenizers --family novelai_glm

下載器會寫入存放庫的 tokenizers/ 目錄。如果 TOKENIZER_ASSET_DIR 指向其他位置，請將下載的家族目錄複製到該處。安裝或修復資產後請重新啟動 TomoriBot，因為執行階段會快取載入失敗的狀態。

安全的 fetch_url 後備與 DuckDuckGo 的 web_search 後備均在處理程序內執行，因此兩者都不需要額外安裝。

維護、更新與備份

Section titled “維護、更新與備份”

安裝完成之後，主機端指令稿（bun run update、bun run backup、 bun run restore-backup、bun run nuke-db、bun run rotate-keys……）與更新、備份流程都放在 維護與備份頁面。如果你正準備拉取新版本，請先從 維護與備份開始。