Atuin Shell 历史搜索¶

一句话说明： Atuin 用 SQLite 数据库替换 Shell 原生历史记录，支持全文搜索、跨设备同步、上下文感知过滤，让命令历史变成真正可检索的知识库。

为什么要学¶

全文搜索 — 模糊匹配、正则搜索，比 Ctrl+R 强大百倍
跨设备同步 — 端到端加密同步，在任何机器上找到历史命令
上下文感知 — 按目录、会话、主机名过滤，精准定位命令
丰富元数据 — 每条命令记录执行时间、退出码、持续时长、工作目录
统计分析 — 了解自己的命令使用习惯，优化工作流

核心概念详解¶

与原生历史对比¶

特性	Bash/Zsh 历史	Atuin
存储格式	纯文本文件	SQLite 数据库
搜索方式	前缀匹配	全文/模糊/正则
元数据	仅命令文本（zsh 有时间戳）	时间、目录、退出码、时长、主机
跨设备	不支持	端到端加密同步
容量	通常 1000-10000 条	无限制
过滤	无	目录/会话/主机/退出码

搜索模式¶

模式	说明	适用场景
`prefix`	前缀匹配	记得命令开头
`fulltext`	全文包含	记得命令中某个词
`fuzzy`	模糊匹配	只记得大概
`skim`	skim 风格模糊	交互式筛选

过滤维度¶

维度	说明
Global	所有主机、所有目录
Host	仅当前主机
Session	仅当前 shell 会话
Directory	仅当前工作目录

同步架构¶

本地 SQLite ←→ 加密 ←→ Atuin 服务器 ←→ 解密 ←→ 另一设备

所有数据在客户端加密，服务器无法读取命令内容。

安装与配置¶

安装¶

# 推荐方式（自动配置 shell 集成）
curl --proto '=https' --tlsv1.2 -LsSf https://setup.atuin.sh | sh

# macOS
brew install atuin

# Linux (cargo)
cargo install atuin

# Arch Linux
pacman -S atuin

Shell 集成¶

# Bash（添加到 ~/.bashrc）
eval "$(atuin init bash)"

# Zsh（添加到 ~/.zshrc）
eval "$(atuin init zsh)"

# Fish（添加到 config.fish）
atuin init fish | source

# Nushell
# 按文档添加到 config.nu

导入已有历史¶

# 导入当前 shell 历史
atuin import auto

# 指定导入源
atuin import bash
atuin import zsh
atuin import fish

同步设置（可选）¶

# 注册账户（使用官方服务器）
atuin register -u username -e email@example.com -p password

# 或使用自托管服务器
atuin register -u username -e email -p password

# 登录
atuin login -u username -p password

# 同步
atuin sync

验证¶

atuin --version
# atuin 18.4.0

# 查看状态
atuin status

快速上手¶

基本搜索¶

# 交互式搜索（替代 Ctrl+R）
# 按 Ctrl+R 或 上箭头（取决于配置）

# 命令行搜索
atuin search "docker"
atuin search "git commit"

# 模糊搜索
atuin search --search-mode fuzzy "dckr bld"

交互界面操作¶

按 Ctrl+R 进入 Atuin 搜索界面：

快捷键	操作
输入文字	搜索/过滤
`↑` / `↓`	浏览结果
`Enter`	选择并执行
`Tab`	选择但不执行（填入命令行）
`Ctrl+R`	切换过滤范围（Global/Host/Session/Directory）
`Ctrl+S`	切换搜索模式（prefix/fulltext/fuzzy）
`Esc`	退出

统计信息¶

# 查看命令统计
atuin stats

# 最常用命令
atuin stats --count 20

输出示例：

[▮▮▮▮▮▮▮▮▮▮] 520 git
[▮▮▮▮▮▮▮   ] 380 cd
[▮▮▮▮▮▮    ] 310 ls
[▮▮▮▮▮     ] 245 python
[▮▮▮▮      ] 198 docker

进阶用法¶

1. 配置文件¶

配置文件路径：~/.config/atuin/config.toml

## 搜索设置
[search]
# 默认搜索模式: prefix, fulltext, fuzzy, skim
filter_mode = "fuzzy"
# 默认过滤范围: global, host, session, directory
filter_mode_shell_up_key_binding = "directory"

## 同步设置
[sync]
# 同步频率（秒）
sync_frequency = "5m"
# 同步地址（自托管时修改）
sync_address = "https://api.atuin.sh"

## UI 设置
[ui]
# 搜索界面样式: compact, full
style = "compact"
# 显示命令执行时间
show_duration = true
# 显示退出码
show_exit = true
# 内联高度（行数）
inline_height = 30

## 历史设置
[history]
# 不记录的命令模式
secrets_filter = true
# 不记录以空格开头的命令
ignore_commands = ["ls", "cd", "pwd"]

2. 高级搜索技巧¶

# 按目录过滤
atuin search --cwd /home/user/project "make"

# 按退出码过滤（只看失败命令）
atuin search --exit 1

# 按时间范围
atuin search --after "2024-01-01" --before "2024-06-01" "deploy"

# 按主机过滤
atuin search --host "prod-server" "systemctl"

# 组合过滤
atuin search --cwd ~/project --exit 0 --after "yesterday" "test"

3. 自托管同步服务器¶

# Docker 部署 Atuin 服务器
docker run -d \
  --name atuin-server \
  -p 8888:8888 \
  -v atuin-data:/config \
  -e ATUIN_HOST=0.0.0.0 \
  -e ATUIN_PORT=8888 \
  -e ATUIN_DB_URI=sqlite:///config/atuin.db \
  ghcr.io/atuinsh/atuin:latest server start

客户端配置指向自托管：

# ~/.config/atuin/config.toml
[sync]
sync_address = "http://your-server:8888"

4. 脚本集成¶

# 在脚本中搜索历史
atuin search --format "{command}" --limit 1 "docker-compose up"

# 导出历史
atuin history list --format json > history_backup.json

# 最近失败的命令
atuin search --exit 1 --limit 10 --format "{time}\t{command}\t{duration}"

5. 敏感命令过滤¶

# config.toml
[history]
secrets_filter = true  # 自动过滤含密码/token 的命令

# 自定义忽略模式
# 以空格开头的命令不记录（与 bash HISTCONTROL 类似）

# 手动删除敏感记录
atuin search "password" | atuin history delete

6. 多 Shell 共享¶

Atuin 支持同时在 bash/zsh/fish 中使用，历史记录自动合并：

# 在 zsh 中执行的命令，切换到 fish 后也能搜索到
# 自动按时间排序，标记来源 shell

常见问题与排错¶

Q: Ctrl+R 没有调出 Atuin¶

确认 shell 集成已添加到配置文件的最后：

# 检查是否正确初始化
eval "$(atuin init zsh)"  # 必须在 .zshrc 末尾

重新打开终端或 source ~/.zshrc。

Q: 同步失败¶

# 检查同步状态
atuin status

# 强制同步
atuin sync --force

# 检查网络
curl -I https://api.atuin.sh

Q: 历史记录太多导致搜索慢¶

# Atuin 使用 SQLite FTS，通常不会慢
# 如果确实很慢，可以限制搜索范围
atuin search --limit 100 --after "last month" "query"

Q: 如何禁用上箭头绑定¶

# config.toml
[keys]
scroll_exits = false

# 或在 init 时指定
eval "$(atuin init zsh --disable-up-arrow)"

Q: 与 fzf 冲突¶

# 在 .zshrc 中，将 atuin init 放在 fzf 配置之后
# Atuin 会覆盖 Ctrl+R 绑定
source ~/.fzf.zsh
eval "$(atuin init zsh)"

参考资源¶

官方文档：https://docs.atuin.sh
GitHub 仓库：https://github.com/atuinsh/atuin
配置参考：https://docs.atuin.sh/configuration/config/
自托管指南：https://docs.atuin.sh/self-hosting/server-setup/
Discord 社区：https://discord.gg/jR3tfchVvW
博客：https://blog.atuin.sh