wiki/docker.md

Hajimi 应用 Docker 部署指南 🚀

欢迎使用 Hajimi 应用！本指南将引导您使用 Docker 在不同环境（本地电脑、远程服务器、NAS）中快速部署 Hajimi 应用。

1. 准备工作 🛠️

1.1 安装 Docker

请确保您的系统（Windows, macOS, Linux）已安装 Docker。

• Windows/Linux 用户：推荐安装 Docker Desktop。

• macOS 用户：除了 Docker Desktop 外，也可以考虑使用 OrbStack (一款高性能的 Docker Desktop 替代品)。

• 下载地址：Docker 官方网站

• 安装步骤：按照官方指引完成安装。

1.2 获取配置文件

下载部署所需的两个核心配置文件：

.env文件下载

docker-compose.yaml文件下载

1.3 创建项目目录并放置配置文件 📂

在您选择的位置创建一个专门用于部署 Hajimi 的文件夹，并将下载的 .env 和 docker-compose.yaml 文件放入该文件夹中。

• Mac/Linux：在终端执行 mkdir ~/hajimi-app && cd ~/hajimi-app
• Windows：
  • 在命令提示符执行 mkdir C:\Users\<用户名>\hajimi-app && cd C:\Users\<用户名>\hajimi-app （请将 <用户名> 替换为您的 Windows 用户名）
  • 或在 PowerShell 执行 mkdir $HOME\hajimi-app; cd $HOME\hajimi-app 或者，您也可以直接在桌面或其他位置创建 hajimi-app 文件夹，然后将下载的两个文件移动进去。

重要提示：后续的所有命令行操作，除非特别说明，都应在此 hajimi-app 文件夹内执行。

1.4 通用配置步骤 ⚙️

在启动服务之前，您需要根据自己的需求修改配置文件。请使用文本编辑器打开 hajimi-app 文件夹中的 .env 和 docker-compose.yaml 文件。

1.4.1 修改 .env 文件

这是存放敏感信息和应用基本配置的地方。

# --- 必填项 ---
# 设置你的 Gemini API 密钥，可以设置多个，用英文逗号隔开
GEMINI_API_KEYS=key1,key2,key3  # <= 替换为你的真实密钥

# 设置应用的登录密码
PASSWORD=123   # <= 设置一个安全的密码，默认密码123，请务必修改！

# --- 可选项 (Vertex AI) ---
# 是否启用 Google Vertex AI (默认关闭)
ENABLE_VERTEX=false           # <= 如需开启，改为 true

# 如果开启 Vertex AI，请填入完整的 Google Cloud 服务账号 JSON 密钥内容
# 注意：整个 JSON 内容需要包含在英文单引号 ' ' 内部
GOOGLE_CREDENTIALS_JSON='JSON 密钥内容' # <= 粘贴你的 JSON 密钥内容

提示：.env 文件中还包含更多高级配置项，您可以根据末尾的 “附录：参考环境变量详情” 按需调整。

1.4.2 按需修改 docker-compose.yaml 文件

这个文件定义了 Docker 如何运行 Hajimi 服务。主要关注以下几点：

• 端口映射：如果 7860 端口已被其他应用占用，您需要修改端口映射。
• 网络代理：如果您的部署环境无法直接访问 Google API (或其他所需外部服务)，需要配置代理。
• **数据持久化 (重要！)**：默认配置已启用数据持久化。
• 时区：默认配置为中国时区。

services:
  hajimi-app: # 服务名，可自定义
    image: beijixingxing/hajimi:latest
    container_name: hajimi-app  # 固定容器名方便监控
    labels:
      - "com.centurylinklabs.watchtower.enable=true"  # 启用自动更新
    ports:
      - "7860:7860" # 端口映射：冒号左边是宿主机端口（可改），右边是容器内端口（固定7860）。
                    # 如果 7860 端口冲突，修改冒号左边的数字，例如 "17860:7860"
    env_file:
      - .env  # 加载 .env 文件中的环境变量
    environment:
      - TZ=Asia/Shanghai # 时区配置，默认中国时区。如需修改，例如：America/New_York
      - ENABLE_STORAGE=true # 应用层面的数据持久化开关，配合 volumes 使用

      # --- 网络代理 (按需取消注释并修改) ---
      # 如果需要 HTTP 代理:
      # HTTP_PROXY: "http://your_proxy_address:port"  # <= 例如 "http://127.0.0.1:7890"
      # 如果需要 HTTPS 代理 (通常与 HTTP 代理相同):
      # HTTPS_PROXY: "http://your_proxy_address:port" # <= 例如 "http://127.0.0.1:7890"
      # 注意：在 Windows/Mac 的 Docker Desktop 环境下，若代理在宿主机上，可尝试使用 "host.docker.internal"作为地址，
      # 例如: HTTP_PROXY: "http://host.docker.internal:7890"
      # 在 Linux 服务器上，请直接填写代理服务器的 IP 地址和端口。

    volumes: # 数据持久化配置
      - ./settings:/hajimi/settings # 将容器内的 /hajimi/settings 目录映射到当前项目文件夹下的 settings 子目录。
                                   # 这会保存应用的所有重要配置和数据，即使容器更新或重启也不会丢失。
                                   # 首次启动后，您会在 hajimi-app 文件夹下看到一个新创建的 settings 文件夹。
    restart: unless-stopped # 容器退出时自动重启，除非是手动停止的。

  # 🆙 自动更新监控服务（默认每小时检查一次）
  watchtower:
    image: containrrr/watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock  # 必须的Docker连接配置
    environment:
      - TZ=Asia/Shanghai # 时区配置
      - WATCHTOWER_LABEL_ENABLE=true  # 只监控带有 "com.centurylinklabs.watchtower.enable=true" 标签的容器
      - WATCHTOWER_POLL_INTERVAL=3600  # 检查间隔秒数（3600秒 = 1小时）
      - WATCHTOWER_CLEANUP=true  # 更新后自动删除旧镜像
    restart: unless-stopped

配置完成后，请保存文件。

2. 选择部署方式并启动服务 ▶️

根据您的环境选择相应的部署方式：

2.1 本地电脑部署 (Docker Desktop / OrbStack)

1. 打开终端 (Mac/Linux) 或命令提示符/PowerShell (Windows)。
2. 进入项目目录：使用 cd 命令切换到您之前创建的 hajimi-app 文件夹。
   • **示例 (Mac/Linux)**：cd ~/hajimi-app
   • **示例 (Windows CMD)**：cd C:\Users\<用户名>\hajimi-app
   • **示例 (Windows PowerShell)**：cd $HOME\hajimi-app
3. 启动服务：执行以下命令以后台模式启动服务。

   docker compose up -d
   

   Docker 会自动拉取镜像并根据 docker-compose.yaml 和 .env 文件启动容器。

2.2 远程服务器部署 (SSH)

1. 使用 SSH 工具（如 ssh 命令、PuTTY、Termius 等）连接到您的远程服务器。
2. 创建并进入项目目录：

   # 创建目录 (路径可自定义) 并进入该目录
   mkdir -p /path/to/your/hajimi-app && cd /path/to/your/hajimi-app
   # 例如: mkdir -p /opt/hajimi-app && cd /opt/hajimi-app
   

3. 直接下载配置文件：

   # 下载 .env 文件模板
   wget https://raw.githubusercontent.com/beijixingxing/hajimi/main/wiki/docker/.env
   
   # 下载 docker-compose.yaml 文件
   wget -O docker-compose.yaml https://raw.githubusercontent.com/beijixingxing/hajimi/main/wiki/docker/docker-compose.yaml
   

   或使用 curl：

   curl -o .env https://raw.githubusercontent.com/beijixingxing/hajimi/main/wiki/docker/.env
   curl -o docker-compose.yaml https://raw.githubusercontent.com/beijixingxing/hajimi/main/wiki/docker/docker-compose.yaml
   

4. 重要：编辑配置文件 使用文本编辑器（如 nano 或 vim）修改下载的 .env 文件和 docker-compose.yaml 文件。
   • 必须修改 .env 文件：

     nano .env
     

     至少需要修改 GEMINI_API_KEYS 和 PASSWORD。根据需要调整其他配置。
   • 按需修改 docker-compose.yaml 文件（例如端口、代理）：

     nano docker-compose.yaml
     

     参考 “1.4.2 按需修改 docker-compose.yaml 文件” 部分的说明。
5. 验证文件：

   ls -l  # 应看到 .env 和 docker-compose.yaml 两个文件
   cat .env # 检查 .env 配置文件内容是否已按需修改
   

6. 启动服务：在 SSH 终端中，确保您位于项目目录下，执行启动命令。

   docker compose up -d
   

2.3 NAS 部署 (通过 Docker Compose UI)

注意：不同 NAS 品牌的 Docker UI（如群晖的 Container Manager, QNAP 的 Container Station）操作略有不同，以下为通用步骤。

1. 通过 NAS 的文件管理工具（如 File Station）在 Docker 应用的数据存储区（通常是 /volume1/docker/ 或类似路径）创建一个 hajimi 或 hajimi-app 文件夹。
2. 将您在本地电脑上按照 “1.4 通用配置步骤” 修改好的 .env 和 docker-compose.yaml 文件上传到 NAS 上刚创建的文件夹中。
3. 打开 NAS 的 Docker 管理应用（如 Container Manager）。
4. 寻找 “项目” (Project)、“应用” (Application) 或 “Compose” 相关的选项。
5. 选择 “创建” (Create) 或 “导入” (Import)。
6. 设置项目名称（如 hajimi），并选择已上传 docker-compose.yaml 文件所在的文件夹路径。
7. 系统通常会自动识别 docker-compose.yaml 文件。确认配置无误后，点击 “创建”、“部署” 或 “运行”。
8. NAS 的 Docker UI 会根据配置文件拉取镜像并启动容器。

3. 访问与验证 ✅

服务启动后，稍等片刻让应用完全启动。

1. 本地访问：打开浏览器，访问 http://localhost:7860（如果您修改了端口，请使用修改后的端口）。
2. 服务器/NAS 访问：打开浏览器，访问 http://<服务器或NAS的IP地址>:7860（请将 <服务器或NAS的IP地址> 替换为实际 IP，端口同样根据配置修改）。
3. API 端点：应用的 API (兼容 OpenAI 格式) 可以在以下地址访问：http://<访问地址>:7860/v1

看到登录界面并能使用您在 .env 文件中设置的 PASSWORD 成功登录，即表示部署成功！

4. 常见问题与解决 (FAQ) ❓

4.1 Q1: 启动时提示端口已被占用 (Port is already allocated)

• 原因：7860 端口（或其他您配置的端口）已被系统上另一个程序使用。
• 排查：
  • Mac/Linux：在终端运行 sudo lsof -i :7860
  • Windows：在命令提示符或 PowerShell 运行 netstat -ano | findstr "7860"
• 解决方案：
  • 停止占用该端口的程序。
  • 或者，修改 hajimi-app 文件夹中 docker-compose.yaml 文件里的 ports 部分，将冒号左侧的 7860 改为其他未被占用的端口（如 17860），例如：ports: - "17860:7860"。保存后需要重新启动服务 (docker compose down 然后 docker compose up -d)。

4.2 Q2: 应用无法连接外部服务 (如 Google API)

• 原因：部署环境的网络无法直接访问所需服务，通常需要设置网络代理。
• 解决方案：
  • 确认代理：确保您有可用的 HTTP/HTTPS 代理服务器地址和端口。
  • 配置代理：编辑 hajimi-app 文件夹中的 docker-compose.yaml 文件，在 hajimi-app 服务的 environment 部分取消 HTTP_PROXY 和 HTTPS_PROXY 的注释 (#)，并填入您的代理地址。例如:

    environment:
      # ... 其他环境变量 ...
      HTTP_PROXY: "http://192.168.1.100:7890"
      HTTPS_PROXY: "http://192.168.1.100:7890"
      # 如果代理在宿主机上 (Docker Desktop for Win/Mac), 可尝试:
      # HTTP_PROXY: "http://host.docker.internal:7890"
      # HTTPS_PROXY: "http://host.docker.internal:7890"
    

  • 重启服务：保存文件后，在项目目录下执行 docker compose down 然后 docker compose up -d。
  • 无需代理：如果您的网络环境不需要代理，请确保 HTTP_PROXY 和 HTTPS_PROXY 配置被注释掉（前面有 #）或直接删除。

5. 更新指南 🔄

5.1 自动更新 (内置)

docker-compose.yaml 文件中已包含 Watchtower 服务，用于自动检测并更新 Hajimi 应用的 Docker 镜像。默认设置是每小时检查一次。如果检测到新版本，它会自动拉取并重启容器。

5.2 手动更新

如果您想立即更新到最新版本或禁用了自动更新，可以按以下步骤手动更新：

1. 进入项目目录：使用 cd 命令切换到包含 docker-compose.yaml 文件的 hajimi-app 目录。

   # 示例 (路径需替换为您的实际路径)
   cd /path/to/your/hajimi-app
   

2. 拉取最新镜像：

   docker compose pull hajimi-app # 或者直接 docker compose pull，会拉取所有服务的最新镜像
   

   这将只拉取 hajimi-app 服务的新镜像版本（如果存在）。

3. 停止并重新创建容器：

   # 停止当前运行的容器
   docker compose down
   # 使用新镜像重新创建并启动容器
   docker compose up -d
   

   或者，更简洁的方式是直接执行 docker compose up -d --pull，Compose 会先尝试拉取新镜像，然后如果镜像有更新，会自动重新创建容器。

4. 可选的强制清理命令（仅在遇到问题时使用）：

   # 警告：以下命令会停止并删除容器、网络。 --rmi all 会删除服务相关的镜像。
   # 请谨慎操作，并确保您了解其影响。
   # docker compose down --rmi all
   
   # 然后重新拉取并启动
   # docker compose pull
   # docker compose up -d
   

建议：首次部署时，尽量使用默认配置（除了必要的 API 密钥和密码），确保服务能正常运行。稳定运行后，再根据需要调整端口、代理或其他高级配置。

---

附录：参考配置文件详情

以下是 .env 和 docker-compose.yaml 文件的参考内容，其中包含更多可配置项的说明。在实际部署中，您主要通过修改 hajimi-app 目录下的这两个文件来进行配置。

A.1 参考环境变量详情 (.env 文件)

# --- 🌟 基础安全配置 ---
# 访问密码，用于访问服务的身份验证 (必填，请修改为强密码)
PASSWORD=123
# Web UI修改设置密码，如果留空，则默认值为 PASSWORD 的值
WEB_PASSWORD=

# --- ⏰ 时区配置 ---
# (此项通常在 docker-compose.yaml 中配置，此处列出供参考，但 .env 文件中的 TZ 不会被 Hajimi 应用直接使用)
# TZ=Asia/Shanghai

# --- 🤖 AI Studio核心配置 ---
# 用英文逗号分隔多个API KEY，可使用多个Gemini API密钥 (必填)
GEMINI_API_KEYS=key1,key2,key3
# 每分钟最多请求次数，限制系统每分钟接收的请求数量
MAX_REQUESTS_PER_MINUTE=30
# 每天每个IP的请求上限，防止单个 IP 过度请求
MAX_REQUESTS_PER_DAY_PER_IP=600
# 假装实时传输，用于解决某些情况下客户端断开连接的问题
FAKE_STREAMING=true
# 每个KEY每天最多用100次，限制单个 API 密钥在一天内的使用次数
API_KEY_DAILY_LIMIT=100
# 生成迷惑字符串，可在转发消息中添加随机字符串伪装消息，防止被检测
RANDOM_STRING=true
# 迷惑字符串长度，随机字符串的长度
RANDOM_STRING_LENGTH=5
# 默认并发请求数，系统默认同时处理的请求数量
CONCURRENT_REQUESTS=1
# 请求失败时增加的并发请求数，请求失败后增加的并发处理数量
INCREASE_CONCURRENT_ON_FAILURE=0
# 允许的最大并发请求数，系统允许同时处理的最大请求数量
MAX_CONCURRENT_REQUESTS=3
# 是否启用联网模式，决定是否使用联网搜索功能
SEARCH_MODE=false
# 联网模式提示词，在联网搜索时的提示信息
SEARCH_PROMPT='（使用搜索工具联网搜索，需要在content中结合搜索内容）'
# 需要屏蔽的模型名称，多个模型用英文逗号分隔
BLOCKED_MODELS=
# 空响应重试次数，当请求返回空响应时的重试次数
MAX_EMPTY_RESPONSES=5

# --- 📋 白名单配置 ---
# 模型白名单，仅允许列表中的模型通过，多个用英文逗号分隔 (留空则不限制)
WHITELIST_MODELS=
# 请求头User-Agent白名单模式，仅允许特定的User-Agent访问 (留空则不限制)
WHITELIST_USER_AGENT=

# --- 📝 缓存配置 ---
# 切换缓存计算方法，默认为 false (使用快速但不精确的缓存键)，true 表示使用精确但稍慢的缓存键
PRECISE_CACHE=false

# 📦 持久化配置（已集成在compose文件里）
# 持久化存储目录，默认为 /hajimi/settings/
STORAGE_DIR=/hajimi/settings/
# 是否启用持久化，默认为 false
ENABLE_STORAGE=false

# --- 🔑 Vertex高级配置 ---
# 是否启用vertex，决定是否使用Vertex AI服务，默认关闭
ENABLE_VERTEX=false
# 填入完整的Google凭证JSON (base64编码或直接JSON字符串)，用于访问Vertex AI服务的凭证
# 如果直接使用JSON字符串，请确保其被英文单引号包裹且内部引号已转义，或考虑将其作为 Docker Secret 管理
GOOGLE_CREDENTIALS_JSON=''

A.2 参考 docker-compose.yaml 文件内容

(此内容已在教程主体部分的 "1.4.2 按需修改 docker-compose.yaml 文件" 中详细展示和解释，此处不再重复，请参考上文。)