原神 & 星穹鐵道 Discord Bot

歡迎將本專案所有或部分程式碼放入你自己的機器人中，只需要在你專案的網頁、README 或任何公開的說明文件放入本專案的作者與連結

Feel free to take all or part of the code to your own bot, just put the author and URL of this project in your project's website, README or any public documentation.

邀請原神小幫手

點擊上圖或邀請連結：https://bit.ly/原神小幫手邀請

Discord 支援伺服器：https://discord.gg/myugWxgRjd

簡介

使用機器人直接在 Discord 聊天頻道內查看原神、星穹鐵道內各項資訊，包含：

• 查詢即時便箋
  • 原神：包含樹脂、洞天寶錢、參數質變儀、探索派遣完成時間...等
  • 星穹鐵道：包含開拓力、委託執行
• 每日早上 8 點開始 Hoyolab 自動簽到 (包含簽到崩壞3、星穹鐵道)
• 自動檢查即時便箋 (原神、星鐵)、樹脂 (開拓力)、寶錢、質變儀、探索派遣，當快額滿時發送提醒
• 查詢深境螺旋紀錄
• 查詢旅行者札記
• 個人紀錄卡片（遊戲天數、成就、神瞳、世界探索度...等等）
• 查詢任意玩家的原神/星穹鐵道角色展示櫃，顯示展示櫃內角色的面板、聖遺物詳情
• 查看原神遊戲內公告，包含活動、卡池資訊
• 採用新的斜線指令，輸入 / 自動彈出指令提示，不需要記憶任何指令的使用方式

使用方式

• 邀請到自己伺服器後，輸入斜線 / 查看各項指令
• 第一次請先使用指令 /cookie設定，Cookie 取得方式：https://bit.ly/3LgQkg0
• 設定自動簽到與樹脂提醒，使用指令 /schedule排程

展示

更多展示圖片、GIF 請參考巴哈介紹文章：https://forum.gamer.com.tw/Co.php?bsn=36730&sn=162433

專案資料夾結構

Genshin-Discord-Bot
├── assets         = 存放素材的資料夾
|   ├── font         = 畫圖所用到的字體
|   └── image        = 畫圖所用到的素材、背景圖
├── cogs         = 存放 discord.py cog 資料夾，這裡有所有的機器人指令
├── cogs_external= 存放自訂的 discord.py cog 資料夾，你可以將自己指令的檔案放在這裡
├── configs      = 存放設定檔的資料夾
├── database     = SQLAlchemy ORM、資料庫操作相關的程式碼
|   ├── dataclass    = 自定義的 data class
|   └── legacy       = 以前的資料庫程式碼，用來遷移舊資料之外沒有用
├── enka_network = 與 Enka Network API 相關的程式碼
|   └── enka_card    = Submodule，與畫 Enka 圖片相關的程式碼
├── genshin_db   = 與 genshin-db API 相關的程式碼 
|   └── models       = 存放 genshin-db 資料的 pydantic 模型
├── genshin_py   = 與 genshin.py 相關的程式碼
|   ├── auto_task    = 與自動排程任務 (例如：簽到) 相關的程式碼
|   ├── client       = 向 API 請求資料相關的程式碼
|   └── parser       = 將 API 的資料轉成 discord embed 格式
├── star_rail    = 星穹鐵道展示櫃程式碼
└── utility      = 一些本專案用到的設定、公用函數、Log、表情、Prometheus...等程式碼

自己安裝 & 架設機器人

網頁端

需要在此步驟取得：

• 機器人 Application ID
• 機器人 Bot token
• 自己的管理伺服器 ID

本地端

第一次使用

1. 安裝 Docker (不會安裝的請自行 Google 教學)
   • Windows：至 Docker 官網 下載並安裝，安裝完成後啟動 Docker Desktop，Windows 桌面右下角會有一隻鯨魚圖示
   • Linux：官網說明，左邊有不同 Distribution 可選

接下來沒特別說明都以 Windows、使用 Powershell 來說明

2. 找到你想放資料的地方，建立機器人資料夾 Genshin-Discord-Bot，然後進入

3. 下載 docker-compose.yml 檔案，放在資料夾內

4. 文字編輯器開啟 docker-compose.yml 檔案，基本上都不用動，只要把你剛剛在 #網頁端 拿到的三個資料填入底下三個欄位即可，其他設定可根據自己的需求再改，完成後保存

   • APPLICATION_ID=123456789
   • TEST_SERVER_ID=123456789
   • BOT_TOKEN=ABCD123456789

5. 在此資料夾開啟 Powershell，輸入底下命令即可運行

docker-compose up

若你想要可以關掉 Powershell 在背景執行的話，則使用

docker-compose up -d

Windows 右下角的鯨魚圖示打開 Docker Desktop 可以隨時管理機器人運行的狀態

註1：當運行後看到 【系統】on_ready: You have logged in as XXXXX 表示參數設置正確並成功啟動，此時機器人會自動同步所有指令到你的測試伺服器，稱為「本地同步」。

註2：若你輸入斜線 / 後看不到指令的話，請嘗試 CTRL + R 重新整理或是完全關閉 Discord 軟體並重啟 Discord。

註3：若要在多個伺服器間使用，請在你機器人的私訊頻道內輸入 $jsk sync，並等待（約幾分鐘）Discord 將指令推送，稱為「全域同步」。

從 v1.2.1 版升級上來

1. 建立新的資料夾 Genshin-Discord-Bot，一樣先照上面做到第 4 步驟
2. 將舊版的 data 資料夾內的資料：bot.db (emoji.json)，複製到新資料夾對應位置
3. 所以現在新資料夾結構如下：

Genshin-Discord-Bot/
    ├── docker-compose.yml
    └── data/
        ├── bot/
        │   └── bot.db
        ├── app_commands.json
        └── emoji.json

4. 回到 Genshin-Discord-Bot 目錄，因為資料庫結構有變動，需要先執行指令
   • Windows (Powershell)：docker run -v ${pwd}/data:/app/data ghcr.io/kt-yeh/genshin-discord-bot:latest python main.py --migrate_database
   • Linux：sudo docker run -v $(pwd)/data:/app/data ghcr.io/kt-yeh/genshin-discord-bot:latest python main.py --migrate_database
5. 完成變更資料庫後，執行 docker-compose up 即可開始運行機器人

檔案說明 & 資料備份

成功運行機器人後，你的資料夾結構應該是這樣：

Genshin-Discord-Bot/
    ├── docker-compose.yml  = docker 設定擋，啟動機器人相關設定都在此檔案
    ├── cogs_external/      = 你可以放自己寫的 discord.py cog 到此目錄
    └── data/               = 機器人運行時產生的資料都放在此目錄
        ├── bot/
        │   └── bot.db         = 資料庫檔案
        ├── font/           = 存放字體資料夾
        ├── image/          = 存放圖片資料夾
        ├── _app_commands.json     = 指令 mention 設定檔案
        ├── _emoji.json            = 表情符號設定檔案
        ├── grafana_dashboard.json = grafana 面板設定檔案 
        └── prometheus.yml         = prometheus 伺服器設定擋

資料都放在 data 資料夾內，備份整個資料夾即可

如何更新

當專案有更新時，到 Genshin-Discord-Bot 目錄開啟 Powershell

1. 抓新版 image

docker-compose pull

2. 重新啟動機器人

docker-compose up -d

表情符號配置說明 (data/emoji.json)

Sentry 配置說明

Admin 管理指令說明

/status：顯示機器人狀態，包含延遲、已連接伺服器數量、已連接伺服器名稱
/system：立即開始每日簽到任務、下載 Enka 展示櫃新素材
/system precense 字串1,字串2,字串3,...：變更機器人顯示狀態(正在玩 ...)，每分鐘隨機變更為設定的其中一個字串，字串數量不限
/maintenance：設定遊戲維護時間，在此時間內自動排程(簽到、檢查樹脂)不會執行
/config：動態改動部分設定的值

Prometheus / Grafana 監控儀錶板說明

remote_write:
- url: https://....(此行填入 Remote Write Endpoint)
  basic_auth:
    username: 123456(此行填入 Username / Instance ID)
    password: XXXXXX(此行填入 Password / API Key)

致謝

• 原神 API 使用自: https://github.com/thesadru/genshin.py
• Discord API 使用自: https://github.com/Rapptz/discord.py
• Enka Network API 使用自: https://github.com/EnkaNetwork/API-docs
• Genshin-DB API 使用自: https://github.com/theBowja/genshin-db
• d.py-ext-prometheus: https://github.com/Apollo-Roboto/discord.py-ext-prometheus