以下信息来自服务器上正在运行的 KodBox 容器（docker inspect kodbox 实测）及其 1Panel 应用目录，教程步骤以这套实际配置为蓝本，密码位置已用占位符替代。

• Docker 与 Docker Compose 已安装（Docker ≥ 20.10，Compose v2）。本服务器实测 Docker 26.1.4 / Compose v2.27.1。
• MySQL 8.0 已按《MySQL Docker Compose 部署图文教程》部署在 1panel-network 网络，根密码已验证；直接复用其 3306 对外端口。
• 一个对外端口 8081（本服务器即 8081，需在云安全组/防火墙放行）。
• 可选的域名与 Nginx/1Panel 反向代理（教程末尾介绍）。

KodBox 需要一个独立数据库。进入 MySQL 容器，用 root 创建库 kodbox 和专用账号（本服务器已按此建好）：

docker exec -it mysql mysql -uroot -p'你的Root密码'

# 在 MySQL 提示符下执行：
CREATE DATABASE IF NOT EXISTS kodbox DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER IF NOT EXISTS 'kodbox'@'%' IDENTIFIED BY '你的KodBox库密码';
GRANT ALL PRIVILEGES ON kodbox.* TO 'kodbox'@'%';
FLUSH PRIVILEGES;
EXIT;

验证：确认账号可登录、库已建成功（本服务器实测 25 张业务表）：

docker exec mysql mysql -uroot -p'你的Root密码' -e   "SELECT user,host FROM mysql.user WHERE user='kodbox'; SHOW GRANTS FOR 'kodbox'@'%';"

本服务器 KodBox 由 1Panel 应用商店创建，Compose 项目目录位于 /opt/1panel/apps/kodbox/kodbox。下方给出一份标准化的、与现网配置一致的 compose 文件，可直接手动创建：

mkdir -p /opt/1panel/apps/kodbox/kodbox
vi /opt/1panel/apps/kodbox/kodbox/docker-compose.yml

粘贴以下内容（端口可按需调整）：

networks:
  1panel-network:              # 复用已有网络
    external: true

services:
  kodbox:
    container_name: kodbox
    image: kodcloud/kodbox:v1.4505    # KodBox 官方镜像
    restart: always                   # 开机自启、崩溃自动拉起
    ports:
      - "8081:80"                     # 宿主机 8081 → 容器 80
    volumes:
      - ./site:/var/www/html          # 站点源码与数据持久化
    networks:
      - 1panel-network
    deploy:
      resources:
        limits:
          cpus: "0.5"                 # 可按需调整
          memory: 512M复制

关键参数说明

cd /opt/1panel/apps/kodbox/kodbox
docker compose up -d          # 后台启动（首次会拉取 kodbox 镜像）
docker compose ps             # 状态应为 Up

验证容器与端口：

docker ps | grep kodbox
docker port kodbox            # 显示 80/tcp -> 0.0.0.0:8081
curl -I http://127.0.0.1:8081  # 应返回 HTTP 200

浏览器访问 http://（服务器IP）:8081，进入 KodBox 安装向导，填写数据库信息（与步骤一创建的一致）：

安装成功后，系统在 site/config/setting_user.php 写入数据库连接配置（本服务器实测）：

$config['database'] = array (
  'DB_TYPE' => 'mysqli',
  'DB_HOST' => '（服务器IP）',   // MySQL 宿主机 IP
  'DB_PORT' => 3306,
  'DB_USER' => 'kodbox',
  'DB_PWD'  => '你的KodBox库密码',
  'DB_NAME' => 'kodbox',
);

再次刷新浏览器，用创建的管理员账号登录，即可开始使用 KodBox 网盘。

查看日志与重启

docker compose logs -f kodbox    # 实时日志
docker compose restart kodbox    # 重启服务

备份（强烈建议）

同时备份站点目录与数据库：

# 1. 站点/上传文件（site 目录即全部站点数据）
tar czf /opt/docker/backup/kodbox-site-$(date +%F).tar.gz -C /opt/1panel/apps/kodbox/kodbox/site .

# 2. 数据库
docker exec mysql mysqldump -uroot -p'你的Root密码' kodbox   > /opt/docker/backup/kodbox-db-$(date +%F).sql

升级镜像

cd /opt/1panel/apps/kodbox/kodbox
docker compose pull kodbox       # 拉取新镜像
docker compose up -d kodbox      # 重建容器（site 卷自动保留）

Q1：访问 http://IP:8081 打不开？

按顺序排查：① 云安全组/防火墙是否放行 8081；② docker ps 容器是否 Up；③ docker port kodbox 是否 0.0.0.0:8081->80；④ curl -I http://127.0.0.1:8081 是否 200；⑤ 是否已改端口而未重建容器。

Q2：安装时“数据库连接失败”？

① 数据库地址端口是否正确；② 账号/密码/库名是否与 MySQL 实际一致；③ KodBox 与 MySQL 是否都能互通（本服务器均走宿主机 IP （服务器IP）:3306，需确认 MySQL 对外 3306 已开放）；④ MySQL 是否正常 docker ps。

Q3：上传大文件失败 / PHP 限制？

KodBox 镜像默认已调大上传限制；若仍失败，检查磁盘剩余空间 df -h，并确认 site/data/files 所在分区足够。也可在 site/config/setting_user.php 中按需覆盖 maxUploadSize 等参数。

Q4：如何为 KodBox 配域名和 HTTPS？

最简单：用 1Panel 创建一个反代网站，把域名指向 http://127.0.0.1:8081，并自动申请/续期 Let’s Encrypt 证书；或在宿主机 Nginx/Caddy 前做一层反向代理并挂证书。不建议直接让 8081 对外明文传输敏感数据。

Q5：数据库连接为什么用宿主机 IP 而不是 mysql:3306？

本服务器是后端 MySQL 源码中填写的地址，走宿主机对外 3306；只要安全组只对内网/白名单开放即可。更安全的方式是把 KodBox 与 MySQL 都放在同一 Docker 网络内，数据库地址填服务名 mysql，端口 3306，不对外暴露库端口。