K7 详细部署教程

K7 是一款为家庭和小型朋友圈设计的自托管媒体服务器。它支持电影、电视剧和音乐，并提供丰富的客户端、个性化设置及联邦功能。本教程将指导您使用 Docker（推荐方式）完成从安装到首次运行的全过程。

1. 准备工作

在开始部署前，请确保您的环境满足以下条件：

1.1 系统要求

  • 支持运行 Docker 的操作系统（Linux、macOS、Windows）。
  • Docker 和 Docker Compose 已安装。
  • 至少 4GB 内存 和 充足的存储空间（用于存放媒体文件和 PostgreSQL 数据库）。

1.2 获取项目文件

从 GitHub 克隆或下载项目代码：

1
2
git clone https://github.com/kaybi-gh/K7.git
cd K7

2. 使用 Docker Compose 部署

这是官方推荐的快速启动方式。

2.1 配置环境变量

复制示例环境变量文件，并设置数据库密码。

1
cp .env.example .env

重要：编辑 .env 文件，务必修改 POSTGRES_PASSWORD 字段，设置一个强密码。

2.2 启动服务

在项目根目录下，运行以下命令：

1
docker compose up -d

该命令将：

  • 拉取所需的 Docker 镜像（ghcr.io/kaybi-gh/k7:latest）。
  • 在后台启动 K7 服务器和依赖的 PostgreSQL 数据库。
  • 将服务映射到主机的 7080 端口（HTTP）。

2.3 查看运行状态

1
docker compose ps

确保两个容器 (k7 和 postgres) 的状态均为 Up (运行中)。

3. 首次运行设置

3.1 访问 Web 界面

打开浏览器，访问 http://localhost:7080。

3.2 完成初始化向导

您将看到首次运行设置页面，需要完成以下关键步骤：

  1. 创建管理员账户：设置您的用户名、电子邮箱和密码。这是服务器的第一个管理员账号。
  2. 配置媒体库：添加您存放电影、电视剧或音乐的本地文件夹路径。您可以在后续设置中随时调整。
  3. 设置元数据语言：选择您偏好的元数据（如简介、海报）抓取语言。

完成向导后，您将进入 K7 的主界面。

4. 基本配置与使用

4.1 添加媒体文件

将您的视频或音频文件放入您在初始化时配置的媒体库文件夹中。K7 会自动扫描并导入元数据。

4.2 客户端连接

  • Web 客户端：通过浏览器访问 http://<您的服务器IP>:7080。
  • 移动/桌面客户端：项目提供 Android、Windows、iOS 和 Mac 客户端，可从对应的应用商店或项目 Release 页面下载。
  • 第三方客户端：K7 支持 OpenSubsonic 协议，您可以使用 Symfonium、Feishin 等应用，通过“设置 -> 外部客户端”生成的应用密码进行连接。

4.3 探索功能

管理员登录后，可以：

  • 管理用户：在管理面板创建新用户、启用访客模式或配置两步验证 (2FA) 和 OIDC 单点登录。
  • 个性化设置：在“服务器设置”中调整全局默认值（布局、播放器行为等）。各用户可在自己的“设置”页面覆盖这些默认值。
  • 查看仪表盘：在“管理 -> 仪表盘”中监控服务器状态和后台任务。

5. 高级配置与运维

5.1 配置文件位置

  • 环境变量：根目录下的 .env 文件控制核心环境参数。
  • 用户数据：包括数据库和媒体库元数据，默认存储在 Docker 卷中。如需备份，请参考 Docker Compose 文件中的 volumes 配置。

5.2 更新 K7

进入项目目录，拉取最新镜像并重新创建容器：

1
2
docker compose pull
docker compose up -d

5.3 联邦功能 (Federation)

K7 支持连接两个独立的 K7 实例（例如您和朋友的服务器），以共享和流式传输远程媒体。此功能需要在两端服务器的管理界面中进行配置和授权。

5.4 集成 AudioMuse AI（可选）

如果您运行了独立的 AudioMuse AI 服务器，可以在 K7 的管理设置中配置其 API 地址，以启用 AI 驱动的音乐发现功能（如情绪电台、相似曲目）。

6. 常见问题排查

  • 端口被占用：编辑 docker-compose.yaml 文件，修改 ports: 下的主机端口映射（例如 "7081:7080"）。
  • 无法访问媒体文件：检查 Docker 容器是否具有读取您媒体文件夹的权限。在 docker-compose.yaml 中 volumes: 部分，确保 :/media 的路径正确映射到宿主机目录。
  • 忘记管理员密码：需要通过进入数据库或使用项目提供的特定工具重置。请参阅官方文档 docs/admin/install.md 部分。
  • 查看日志：运行 docker compose logs -f k7 实时查看服务器日志，有助于诊断启动或运行时错误。

总结

K7 是一个功能现代且注重隐私的媒体服务器。通过上述 Docker 部署步骤，您可以在几分钟内搭建起属于自己的媒体中心。其丰富的个性化选项、强大的客户端支持和独特的联邦功能，使其成为 Jellyfin/Plex 等主流方案之外一个非常值得关注的开源选择。

进一步阅读：项目根目录下的 docs/ 文件夹包含了详细的用户、管理员和开发者指南，是深入使用和定制的宝贵资源。