驗收單 · 2026-10-22 · 约 8 分钟

kikoeru 從零部署到連線完整教學：一次跑通後端與手機客戶端

軟體kikoeru分類工具
版本3.0.9體積5.81M
開發方暂无资料狀態已歸檔

kikoeru 是什麼？

kikoeru 是一款專為音聲愛好者打造的開源自架管理系統。它的核心邏輯很直白：你把收藏的音聲文件放在自己的硬碟或 NAS 上，音聲管理 系統的後端會掃描並建立索引，然後通過 Web 界面、iOS 或 Android 客戶端讓你隨時隨地訪問。

不同於線上音聲平台的受限與廣告轟炸，隱私權 與資源完全由你掌控——所有數據都存在自己的伺服器上，支援離線播放，還能通過內網穿透在外網訪問。適合收藏了大量音聲資源、零基礎 想擁有私有音聲庫的用戶，對不喜歡線上平台限制的發燒友尤其友好。

安裝

手機端 APK 安裝（Android 適用）

你從 kikoeru下載 拿到的客戶端是一個 5.81M 的 APK 文件，包名 com.cnl.kikoeru，最新版本 3.0.9。安裝步驟非常簡單：

  1. 打開手機設定，進入「隱私與安全性」（部分品牌叫「隱私保護」或「安全」）
  2. 找到「未知來源應用程式安裝」，允許你下載 APK 的瀏覽器或檔案管理員進行安裝
  3. 通過瀏覽器下載 APK 文件，點擊下載完成的通知，跟隨提示點擊「安裝」
  4. 安裝完成後打開應用，首次啟動會請求「儲存空間」權限（用來快取音聲），點擊允許即可

如果安裝時提示「應用程式未安裝」，通常是舊版本殘留導致的——先卸載手機上舊版 kikoeru，再重新安裝就好。

前置準備（後端部署）

手機端裝好只是第一步，真正的核心是後端伺服器。在開始部署前，確認你滿足以下條件：

  • 硬體：一台能跑服務的設備，最低 1GB 記憶體就夠（NAS、迷你電腦、雲伺服器都行）
  • 軟體：三種部署方式選一即可——Docker 20+、Node.js 18+、Windows 10+
  • 網路：後端運行的設備和手機在同一區域網路內；如果想在外網訪問，還需要內網穿透或公網 IP

步驟一：部署後端伺服器（三選一）

方式 A：Docker 部署（推薦，最省心）

如果你有 Docker 環境（NAS 上大多自帶，Linux 一條命令裝好），直接用社區維護的官方鏡像：

  1. 在伺服器上創建一個 docker-compose.yml 文件，內容如下：
services:
  kikoeru:
    image: number17/kikoeru:latest
    ports:
      - "8888:8888"
    volumes:
      - ./data:/app/data
      - /你的音聲資料夾:/media/audio:ro
    restart: unless-stopped
  1. 把 /你的音聲資料夾 替換成你實際存放音聲的硬碟路徑
  2. 在文件所在目錄運行 docker compose up -d，等待鏡像下載完成後啟動

方式 B：Windows 單文件部署

不想折騰 Docker 的 Windows 用戶，下載作者打包的單文件 exe：

  1. 從官方發布頁下載 exe 文件和對應的 dist 前端目錄，放在同一個資料夾裡
  2. 雙擊 exe 文件，伺服器會自動啟動，在當前資料夾下生成 data、config 等子資料夾
  3. 如果 Windows 防火牆彈出提示，點擊允許訪問

方式 C：npm 源碼部署（適合開發者）

想自己改代碼或二次開發的話，用 npm 安裝：

  1. 確保安裝了 Node.js 18+，運行 npm install kikoeru-express
  2. 從前端倉庫下載或自己構建 dist 目錄，放在專案根目錄
  3. 運行 npm start 啟動後端，監聽 http://[::]:8888

步驟二：首次配置與音聲庫掃描

後端啟動後，在伺服器本機或同網路設備的瀏覽器打開 http://伺服器IP:8888（Docker 部署的話端口對應 compose 裡的設定），進入 Web 管理界面：

  1. 進入「設定」頁面，找到「根目錄」選項，點擊「添加」把你存放音聲的資料夾路徑填進去（Docker 部署的話用容器內的掛載路徑，比如 /media/audio）
  2. 點擊「開始掃描」，掃描器會遍歷該路徑下的所有文件，建立索引數據庫
  3. 掃描進度會通過 Socket 實時推進，完成後 Web 界面就能看到所有音聲的列表

建議掃描完成後備份一次數據庫（在 data 資料夾下的 SQLite 文件），後續誤操作還能恢復。

步驟三：手機客戶端連線

現在打開你安裝好的 kikoeru APK：

  1. 首次打開會看到「添加伺服器」界面，輸入後端伺服器的地址：http://你的伺服器IP:8888（記得帶協議和端口）
  2. 如果後端開啟了 JWT 認證（預設關閉），把 Web 界面裡設定的密碼填進去
  3. 點擊「測試連線」，顯示綠色「連線成功」就可以保存
  4. 返回主界面，就能看到掃描好的所有音聲列表，點擊即可播放

如果手機和伺服器在同一 Wi-Fi 下，IP 通常是 192.168.x.x 或 10.x.x.x，在伺服器上運行 ipconfig（Windows）或 ifconfig（Linux）就能查到。

常見卡點排查

卡點 1：客戶端連不上伺服器

這是新手最容易遇到的問題，按順序排查：

  1. 先看瀏覽器能不能打開 Web 界面：用手機瀏覽器訪問同一個伺服器地址，瀏覽器也打不開 = 後端沒跑起來或端口沒映射好 → 回頭檢查 Docker 容器狀態、exe 是否在運行、防火牆是否放行 8888 端口
  2. JWT 認證問題：如果 Web 界面能打開但客戶端連不上，先在 Web 設定裡暫時關閉 JWT，測試能不能連上——能的話就是密碼填錯或 Token 過期，重置密碼後再開回
  3. 網路類型差異：Wi-Fi 下能連但 4G/5G 連不上，大概率是運營商封了 8888 這種非標準端口 → 改 Docker compose 或後端設定換成 8080、8443 這類常用端口

卡點 2：顯示「幽靈條目」

有時候你刪了硬碟上的音聲文件，Web 界面還顯示著，點進去播放報錯——這是數據庫條目沒清理：

直接跑一次完整掃描就行，掃描器會自動檢查每個條目的文件是否存在，不存在的標記為待清理，掃描完成後幽靈條目就消失了。這是設計好的機制，不用額外操作。

卡點 3：HTTPS 證書警告

如果在外網訪問時瀏覽器彈出「不安全」警告，是因為用了自簽名證書或證書過期：

最簡單的解法是用 Cloudflare Tunnel 或 frp 這類內網穿透工具，它們會自動處理 HTTPS 證書，不用自己折騰 Let's Encrypt。

進階玩法

搞定基礎部署後，可以設定時掃描任務自動同步新添加的音聲文件，或者用 Cloudflare Tunnel 把伺服器暴露到公網，在外網也能通過手機客戶端訪問自己的私有音聲庫。

本文為個人基於網路公開資料整理編寫，非官方內容，僅供學習交流參考；軟體版權歸原作者所有，請支持正版；使用過程中遇到問題請查閱官方管道，本文不承擔任何責任。

同類驗收報告