Koito音乐追踪系统安装指南

Koito是一款用于追踪个人音乐收听历史的实用工具。本文将详细介绍两种安装Koito的方式：使用Docker容器化部署和从源代码构建安装。无论您是普通用户还是开发者，都能找到适合的安装方案。

Docker容器化部署（推荐方案）

对于大多数用户而言，使用Docker是最简单快捷的部署方式。Docker容器化部署具有环境隔离、依赖管理简单、部署快速等优势。

准备工作

1. 确保系统已安装Docker和Docker Compose
2. 准备一个可用的域名或IP地址用于访问服务

部署步骤

创建一个名为compose.yaml的文件，内容如下：

services:
  koito:
    image: gabehf/koito:latest
    container_name: koito
    depends_on:
      - db
    environment:
      - KOITO_DATABASE_URL=postgres://postgres:your_password@db:5432/koitodb
      - KOITO_ALLOWED_HOSTS=your.domain.com,your_ip:4110
    ports:
      - "4110:4110"
    volumes:
      - ./koito-data:/etc/koito
    restart: unless-stopped

  db:
    image: postgres:16
    container_name: psql
    restart: unless-stopped
    environment:
      POSTGRES_DB: koitodb
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: your_password
    volumes:
      - ./db-data:/var/lib/postgresql/data

配置说明

1. 数据库配置：

   • 将your_password替换为您设置的强密码
   • 数据库将持久化存储在db-data目录中

2. 安全配置：

   • KOITO_ALLOWED_HOSTS应设置为允许访问Koito的域名或IP地址
   • 切勿设置为*，这会带来严重的安全风险

3. 数据持久化：

   • Koito的配置文件将存储在koito-data目录中

启动服务

执行以下命令启动服务：

docker-compose up -d

服务启动后，可通过配置的域名或IP地址（端口4110）访问Koito。

从源代码构建安装

对于开发者或需要自定义功能的用户，可以选择从源代码构建安装Koito。

系统要求

1. 类Unix操作系统（Linux/macOS）
2. 已安装PostgreSQL数据库（版本12+）
3. 开发工具链

安装依赖

在基于Debian/Ubuntu的系统上：

sudo apt update
sudo apt install -y libvips-dev make npm
sudo npm install --global yarn

对于其他Linux发行版或macOS，需要根据系统文档安装相应依赖。

构建过程

1. 获取源代码：

git clone https://github.com/gabehf/koito && cd koito

2. 执行构建：

make build

构建过程会自动处理前端和后端的编译工作。

运行服务

构建完成后，使用以下命令启动服务：

KOITO_DATABASE_URL=postgres://postgres:your_password@postgres_ip:5432/koitodb \
KOITO_ALLOWED_HOSTS=your.domain.com,your_ip:4110 \
./koito

访问服务

启动成功后，在浏览器中访问http://localhost:4110即可使用Koito。

常见问题解答

Q：为什么推荐使用Docker部署？ A：Docker能解决环境依赖问题，简化部署流程，且便于后续升级维护。

Q：如何确保数据安全？ A：建议定期备份db-data和koito-data目录，并确保数据库密码强度足够。

Q：服务启动后无法访问怎么办？ A：检查防火墙设置，确保4110端口开放；验证KOITO_ALLOWED_HOSTS配置是否正确。

Q：性能优化建议？ A：对于生产环境，建议将PostgreSQL部署在独立服务器上，并根据数据量调整数据库配置参数。

结语

无论选择哪种安装方式，Koito都能帮助您有效追踪音乐收听历史。Docker方式适合快速部署使用，源代码构建方式则更适合开发者进行二次开发。建议初次使用的用户优先选择Docker部署方案。