Docker 部署 Komari 详细教程

轻量级自托管服务器监控工具 · Lightweight Self-hosted Server Monitoring Tool

一、Komari 简介

1.1 什么是 Komari

Komari 是一款轻量级的自托管服务器监控工具，旨在提供简单、高效的服务器性能监控解决方案。它支持通过 Web 界面查看服务器状态，并通过轻量级 Agent 收集数据。

1.2 核心特性

• 🪶 轻量高效：低资源占用，适合各种规模的服务器
• 🏠 自托管：完全掌控数据隐私，部署简单
• 🖥️ Web 界面：直观的监控仪表盘，易于使用
• 📊 实时监控：CPU、内存、磁盘、网络实时数据
• 🎨 丰富主题：支持多种社区主题，界面美观
• 🔌 多节点：支持同时监控多台服务器
• 📜 开源免费：MIT 协议，可自由使用和修改

1.3 适用场景

• 个人服务器、VPS 监控
• 小型工作室多台服务器统一管理
• NAS、家庭实验室监控
• 学习 Docker 和服务器运维

1.4 项目信息

项目	信息
GitHub 地址	github.com/komari-monitor/komari
官方文档	komari-document.pages.dev
在线演示	ss.akz.moe
开源协议	MIT

二、部署前准备

2.1 服务器要求

配置项	最低要求	推荐配置
CPU	1 Core	1 Core+
内存	512 MB	1 GB+
硬盘	1 GB	5 GB+
系统	Linux	Ubuntu 20.04+ / Debian 11+

2.2 安装 Docker

如果服务器未安装 Docker，使用以下命令一键安装：

curl -fsSL https://get.docker.com | sh

国内服务器推荐使用镜像加速：

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh --mirror Aliyun

验证 Docker 安装：

docker --version
docker compose version

2.3 放行防火墙端口

Komari 默认使用 25774 端口，需要在防火墙和安全组中放行：

# Ubuntu/Debian (ufw)
ufw allow 25774/tcp

# CentOS (firewalld)
firewall-cmd --permanent --add-port=25774/tcp
firewall-cmd --reload

同时记得在云服务商控制台的安全组中放行 25774 端口！

三、Docker 部署 Komari

3.1 创建数据目录

为了数据持久化，建议先创建数据目录：

mkdir -p /opt/komari/data
cd /opt/komari

3.2 方式一：docker run 部署（最简单）

使用最简单的 docker run 命令部署：

docker run -d \
  --name komari \
  --restart unless-stopped \
  -p 25774:25774 \
  -v $(pwd)/data:/app/data \
  -e ADMIN_USERNAME=admin \
  -e ADMIN_PASSWORD=your_secure_password \
  ghcr.io/komari-monitor/komari:latest

3.3 方式二：docker compose 部署（推荐）

使用 docker compose 部署更便于管理：

创建 compose.yaml 文件：

cat > compose.yaml << 'EOF'
services:
  komari:
    image: ghcr.io/komari-monitor/komari:latest
    container_name: komari
    restart: unless-stopped
    ports:
      - "25774:25774"
    volumes:
      - ./data:/app/data
    environment:
      # 可选：自定义初始管理员账号
      - ADMIN_USERNAME=admin
      - ADMIN_PASSWORD=your_secure_password
EOF

启动容器：

docker compose up -d

3.4 国内服务器镜像加速

国内服务器拉取镜像可能较慢，可以使用加速镜像：

# 1ms.run 加速镜像
image: ghcr.1ms.run/komari-monitor/komari:latest

# 阿里云镜像
image: registry.cn-hangzhou.aliyuncs.com/komari/komari:latest

# DockerHub 镜像
image: docker.io/komari/komari:latest

3.5 验证部署

查看容器状态：

docker ps | grep komari

查看容器日志（获取初始密码）：

docker logs komari

3.6 常用 Docker 命令

# 查看容器状态
docker ps -a | grep komari

# 启动容器
docker start komari

# 停止容器
docker stop komari

# 重启容器
docker restart komari

# 查看日志
docker logs -f komari

# 进入容器
docker exec -it komari bash

# 删除容器
docker rm -f komari

# 更新到最新版本
docker compose pull
docker compose up -d

四、初始配置

4.1 访问 Web 界面

部署完成后，浏览器访问：

http://你的服务器IP:25774

4.2 登录

使用以下任一方式登录：

• 自定义账号：使用 docker run/compose 中设置的 ADMIN_USERNAME 和 ADMIN_PASSWORD
• 默认账号：未设置时，用户名为 admin，密码查看容器日志：docker logs komari

4.3 修改默认密码

4.4 修改面板端口（可选）

如果需要修改默认端口，编辑 compose.yaml：

services:
  komari:
    image: ghcr.io/komari-monitor/komari:latest
    container_name: komari
    restart: unless-stopped
    ports:
      - "8888:25774"  # 将 8888 修改为你想要的端口
    volumes:
      - ./data:/app/data
    environment:
      - ADMIN_USERNAME=admin
      - ADMIN_PASSWORD=your_secure_password

重启容器：

docker compose down
docker compose up -d

五、添加监控节点

5.1 创建临时节点

5.2 获取 Agent 安装命令

命令格式类似：

bash <(curl -sL https://raw.githubusercontent.com/komari-monitor/komari-agent/main/install.sh) \
  -e http://你的服务器IP:25774 \
  -t HxrV90Hp7ZB5Vnw2HHpWwI

六、安装 Agent

6.1 Linux 一键安装（推荐）

在被监控的 Linux 服务器上执行：

bash <(curl -sL https://raw.githubusercontent.com/komari-monitor/komari-agent/main/install.sh) \
  -e http://你的服务器IP:25774 \
  -t 你的节点TOKEN

安装成功后，Agent 会作为 systemd 服务运行：

# 查看 Agent 状态
systemctl status komari-agent

# 查看 Agent 日志
journalctl -u komari-agent -f

6.2 手动安装 Agent（适用于下载失败）

如果一键脚本下载失败，可以手动安装：

# 重命名文件
mv komari-agent-linux-amd64 komari-agent

# 赋予执行权限
chmod +x komari-agent

# 验证文件
ls -lh komari-agent
file komari-agent

启动 Agent（临时运行）：

./komari-agent -e http://你的服务器IP:25774 -t 你的节点TOKEN

使用 systemd 持久化运行：

cat > /etc/systemd/system/komari-agent.service << 'EOF'
[Unit]
Description=Komari Agent
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/komari-agent -e http://你的服务器IP:25774 -t 你的节点TOKEN
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

# 复制二进制文件
sudo cp komari-agent /usr/local/bin/

# 重新加载 systemd
sudo systemctl daemon-reload

# 启动服务
sudo systemctl enable --now komari-agent

# 查看状态
sudo systemctl status komari-agent

6.3 Windows 安装 Agent

从 GitHub 下载 Windows 版本的 Agent，然后：

# 在 PowerShell 中执行
.\komari-agent-windows-amd64.exe -e http://你的服务器IP:25774 -t 你的节点TOKEN

6.4 Docker 方式运行 Agent

如果被监控服务器不方便安装 Agent，也可以使用 Docker：

docker run -d \
  --name komari-agent \
  --restart unless-stopped \
  --network host \
  -e KOMARI_ENDPOINT=http://你的服务器IP:25774 \
  -e KOMARI_TOKEN=你的节点TOKEN \
  ghcr.io/komari-monitor/komari-agent:latest

6.5 验证 Agent 连接

返回 Komari Web 面板，刷新节点列表：

• 节点状态显示「在线」
• 可以看到实时 CPU、内存、磁盘数据
• 节点会自动识别 IP 和地理位置

七、主题与美化

7.1 主题介绍

Komari 支持多种社区主题，让监控面板更美观：

主题	风格	技术栈
Kumo	Cloudflare 风格	Next.js 15 + Tailwind
Light	现代简约	Tailwind + shadcn/ui
Mochi	移动端优化	Vue + TypeScript
Naive	极简轻量	Vue 3 + Naive UI
Next	高度自定义	Next.js + Shadcn UI
PurCarte	磨砂玻璃	Vue 3

7.2 主题下载

访问 社区主题页面 查看所有主题，或访问 Komari GitHub 了解详情。

7.3 安装主题

主题通常以静态文件形式提供，下载后放置在 ./data/themes/ 目录中：

# 进入主题目录
cd /opt/komari/data/themes/

# 下载主题（以 Kumo 为例）
git clone https://github.com/yuanhhs/komari-theme-kumo.git kumo

# 重启 Komari 容器
docker restart komari

在 Komari 面板「设置」→「主题」中选择已安装的主题。

八、高级配置

8.1 数据备份

Komari 的数据存储在 ./data 目录中，定期备份即可：

# 备份数据
tar -czf komari-backup-$(date +%Y%m%d).tar.gz -C /opt/komari data

# 恢复数据
tar -xzf komari-backup-20240101.tar.gz -C /opt/komari/

设置自动备份（crontab）：

# 每天凌晨 3 点备份
0 3 * * * tar -czf /backup/komari-$(date +\%Y\%m\%d).tar.gz -C /opt/komari data

8.2 配置反向代理

使用 Nginx 反向代理并启用 HTTPS：

server {
    listen 80;
    server_name monitor.example.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name monitor.example.com;

    ssl_certificate     /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:25774;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

8.3 更新 Komari

# 拉取最新镜像
docker compose pull

# 重启容器
docker compose up -d

# 或者使用 docker run 方式
docker pull ghcr.io/komari-monitor/komari:latest
docker stop komari
docker rm komari
# 重新运行 docker run 命令

8.4 查看监控数据

在 Komari 主面板可以查看：

• 总览：所有节点的总体状态
• CPU 使用率：实时和历史曲线
• 内存使用：实时占用和历史数据
• 磁盘使用：各分区使用情况
• 网络流量：实时上下行速度和总流量
• 系统负载：Load Average
• 在线状态：节点是否在线

8.5 启用 HTTPS（自签名证书）

如果直接访问 Komari 想要使用 HTTPS，可以通过反向代理实现，参考 8.2 节配置。

九、常见问题

Q1：忘记管理员密码怎么办？

有三种方法重置密码：

方法一：删除数据重新初始化

# 停止容器
docker stop komari

# 备份并删除数据库（保留主题等）
mv /opt/komari/data/db /opt/komari/data/db.bak

# 重启容器，会自动生成新的随机密码
docker start komari
docker logs komari

方法二：编辑环境变量重置

修改 compose.yaml 中的 ADMIN_PASSWORD，重启容器即可重置密码。

Q2：Agent 连接不上？

• 检查网络：确保被监控服务器可以访问 Komari 服务端
• 检查端口：服务端 25774 端口是否开放
• 检查 Token：确保 Token 正确且未被泄露
• 查看 Agent 日志：journalctl -u komari-agent -f

Q3：容器无法启动？

# 查看错误日志
docker logs komari

# 常见原因：
# 1. 端口被占用 - 修改端口
# 2. 权限问题 - 修复 data 目录权限
# 3. 镜像拉取失败 - 使用国内镜像

Q4：如何迁移到新服务器？

Q5：如何修改面板语言？

Komari 默认支持中文和英文。在 Web 面板右上角或个人设置中可以切换语言。

Q6：数据存储在哪里？

数据存储在 Docker 容器内的 /app/data 目录，通过 volume 挂载到宿主机的 ./data 目录，实现数据持久化。

Q7：如何完全卸载？

# 停止并删除容器
docker stop komari
docker rm komari

# 删除数据（谨慎操作！）
rm -rf /opt/komari

# 删除镜像
docker rmi ghcr.io/komari-monitor/komari:latest