linuxserver/hishtory-server 镜像文档

镜像概述和主要用途

linuxserver/hishtory-server 是由 LinuxServer.io 团队构建的 Docker 镜像，用于部署 hiSHtory 服务器。hiSHtory 是一款增强型 shell 历史记录工具，能够在存储命令历史时保留上下文信息（如执行目录、命令成功与否、执行耗时等）。所有数据默认本地存储，并支持端到端加密以实现跨设备同步。

核心功能和特性

LinuxServer.io 镜像特性

• 定期应用更新：确保应用始终保持最新版本
• 灵活用户映射：通过 PUID/PGID 实现容器内用户与宿主机用户权限映射
• 自定义基础镜像：集成 s6 覆盖层，提供可靠的进程管理
• 每周系统更新：基础操作系统定期更新，通过共享层减少存储空间占用、 downtime 和带宽消耗
• 常规安全更新：及时修复安全漏洞，保障服务稳定运行

hiSHtory 核心功能

• 上下文感知存储：记录命令执行目录、退出状态、执行时间等元数据
• 本地优先存储：历史数据默认存储在本地，保护数据隐私
• 端到端加密同步：跨设备同步时采用加密技术，确保数据传输安全
• 多平台支持：兼容主流 shell 环境，支持多设备协同

使用场景和适用范围

• 开发人员：需要跨设备同步命令历史，保留复杂操作上下文的用户
• 系统管理员：需记录服务器操作历史，便于审计和问题排查
• 多设备用户：在多台计算机间无缝切换工作环境的用户
• 命令行重度使用者：希望高效管理、检索和复用历史命令的用户

支持的架构

该镜像通过 Docker manifest 实现多平台支持，直接拉取 lscr.io/linuxserver/hishtory-server:latest 即可获取对应架构的镜像，也可通过标签指定具体架构。

应用设置

1. 在客户端机器安装 hiSHtory 后，向 shell 配置文件（如 .bashrc、.zshrc）添加环境变量：

   export HISHTORY_SERVER=http://<服务器IP或域名>:8080
   

2. 执行初始化命令连接到服务器：

   hishtory init  # 或使用密钥初始化: hishtory init ${SECRET_KEY}
   

更多详情请参考 官方项目文档。

特殊操作模式

只读操作

该镜像支持以只读容器文件系统模式运行，详情请参考 LinuxServer.io 只读文档。

非 Root 用户运行

该镜像支持以非 root 用户身份运行，详情请参考 LinuxServer.io 非 Root 文档。

使用方法和配置说明

docker-compose (推荐)

---
services:
  hishtory-server:
    image: lscr.io/linuxserver/hishtory-server:latest
    container_name: hishtory-server
    environment:
      - PUID=1000               # 用户ID，用于权限映射
      - PGID=1000               # 组ID，用于权限映射
      - TZ=Etc/UTC              # 时区设置，如 Asia/Shanghai
      # 可选：PostgreSQL 数据库连接URI，与SQLite二选一
      - HISHTORY_POSTGRES_DB=postgresql://${HISHTORY_DB_USER}:${HISHTORY_DB_PASS}@hishtory-db:5432/hishtory?sslmode=disable
      # 可选：SQLite数据库路径，需映射持久化卷，与PostgreSQL二选一
      - HISHTORY_SQLITE_DB=/config/hishtory.db
    ports:
      - 8080:8080               # API端口映射
    restart: unless-stopped     # 重启策略

docker cli

docker run -d \
  --name=hishtory-server \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Etc/UTC \
  # 可选：PostgreSQL数据库连接URI
  -e HISHTORY_POSTGRES_DB=postgresql://${HISHTORY_DB_USER}:${HISHTORY_DB_PASS}@hishtory-db:5432/hishtory?sslmode=disable \
  # 可选：SQLite数据库路径
  -e HISHTORY_SQLITE_DB=/config/hishtory.db \
  -p 8080:8080 \
  --restart unless-stopped \
  lscr.io/linuxserver/hishtory-server:latest

参数说明

环境变量与文件（Docker secrets）

可通过 FILE__ 前缀从文件加载环境变量，例如：

-e FILE__MYVAR=/run/secrets/mysecretvariable

上述命令会将 /run/secrets/mysecretvariable 文件内容作为 MYVAR 环境变量的值。

Umask 设置

所有 LinuxServer.io 镜像支持通过 -e UMASK=022 覆盖默认 umask 设置。注意 umask 是权限掩码，通过减法方式调整权限，而非直接设置权限，详情参考 umask 说明。

用户/组标识符（PUID/PGID）

使用卷（-v 参数）时，宿主机与容器间可能出现权限问题。通过指定 PUID 和 PGID，可确保容器内用户与宿主机用户权限一致。获取当前用户的 PUID/PGID：

id your_user

输出示例：

uid=1000(your_user) gid=1000(your_user) groups=1000(your_user)

Docker Mods

![Docker Mods]([] ![Docker Universal Mods]([]

Docker Mods 提供额外功能扩展，可通过上述链接查看适用于该镜像的 Mods 及通用 Mods。

支持信息

容器内 shell 访问

docker exec -it hishtory-server /bin/bash

实时查看容器日志

docker logs -f hishtory-server

获取容器版本号

docker inspect -f '{{ index .Config.Labels "build_version" }}' hishtory-server

获取镜像版本号

docker inspect -f '{{ index .Config.Labels "build_version" }}' lscr.io/linuxserver/hishtory-server:latest

更新信息

通过 Docker Compose 更新

• 更新所有镜像：

  docker-compose pull
  

• 更新单个镜像：

  docker-compose pull hishtory-server
  

• 更新所有容器：

  docker-compose up -d
  

• 更新单个容器：

  docker-compose up -d hishtory-server
  

• 清理旧镜像：

  docker image prune
  

通过 Docker Run 更新

• 更新镜像：

  docker pull lscr.io/linuxserver/hishtory-server:latest
  

• 停止容器：

  docker stop hishtory-server
  

• 删除容器：

  docker rm hishtory-server
  

• 使用原参数重新创建容器（若卷映射正确，配置将保留）
• 清理旧镜像：

  docker image prune
  

镜像更新通知 - Diun

推荐使用 Diun 接收镜像更新通知，不建议使用自动更新容器的工具。

本地构建

如需本地修改或开发：

git clone [***]
cd docker-hishtory-server
docker build \
  --no-cache \
  --pull \
  -t lscr.io/linuxserver/hishtory-server:latest .

在 x86_64 硬件上构建 ARM 变体（反之亦然）：

docker run --rm --privileged lscr.io/linuxserver/qemu-static --reset

注册后，使用 -f Dockerfile.aarch64 指定架构对应的 Dockerfile。

版本历史

• 05.07.25: 基于 Alpine 3.22 重新构建
• 19.12.24: 基于 Alpine 3.21 重新构建
• 26.08.24: 升级至 Go 1.23
• 24.05.24: 基于 Alpine 3.20 重新构建
• 31.01.24: 基于 Alpine 3.19 重新构建
• 19.05.23: 初始发布