From 02049bf68d5389140e62393cd90e310e9e2749e4 Mon Sep 17 00:00:00 2001 From: Bruce Huang Date: Sat, 8 Oct 2022 11:36:49 +0800 Subject: [PATCH] update zh-CN docs (#539) * update zh-CN docs * update zh-CN docs * update zh-CN docs * update zh-CN docs --- README.md | 4 +- docs/config.md | 2 +- docs/docker.md | 6 +- docs/k8s.md | 4 +- docs/zh-CN/README.md | 54 ++++++++--- docs/zh-CN/config.md | 2 +- docs/zh-CN/docker.md | 90 ++++++++++++++++++ docs/zh-CN/k8s.md | 195 ++++++++++++++++++++++++++++++++++++++ docs/zh-CN/key-binding.md | 13 ++- docs/zh-CN/search.md | 2 +- docs/zh-CN/server.md | 93 ++---------------- 11 files changed, 357 insertions(+), 108 deletions(-) create mode 100644 docs/zh-CN/docker.md create mode 100644 docs/zh-CN/k8s.md diff --git a/README.md b/README.md index 70d8333..ebc9fa6 100644 --- a/README.md +++ b/README.md @@ -108,7 +108,7 @@ Alongside the hosted Atuin server, there is also a service which generates activ For example, here is mine: ![](https://api.atuin.sh/img/ellie.png?token=0722830c382b42777bdb652da5b71efb61d8d387) - + If you wish to get your own, after signing up for the sync server, run this ``` @@ -138,6 +138,8 @@ system package manager where possible (pacman, homebrew, etc etc). bash <(curl https://raw.githubusercontent.com/ellie/atuin/main/install.sh) ``` +And then follow [the shell setup](#shell-plugin) + ### With cargo It's best to use [rustup](https://rustup.rs/) to get setup with a Rust diff --git a/docs/config.md b/docs/config.md index dbe48d9..42d8b0b 100644 --- a/docs/config.md +++ b/docs/config.md @@ -96,7 +96,7 @@ key = "~/.atuin-session" ### `search_mode` -Which search mode to use. Atuin supports "prefix", full text and "fuzzy" search +Which search mode to use. Atuin supports "prefix", fulltext and "fuzzy" search modes. The prefix searches for "query\*", fulltext "\*query\*", and fuzzy applies the search syntax [described below](#fuzzy-search-syntax). diff --git a/docs/docker.md b/docs/docker.md index 9b035a6..2cbe75f 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -1,4 +1,4 @@ -## Docker +# Docker There is a supplied docker image to make deploying a server as a container easier. @@ -6,7 +6,7 @@ There is a supplied docker image to make deploying a server as a container easie docker run -d -v "$USER/.config/atuin:/config" ghcr.io/ellie/atuin:latest server start ``` -## Docker Compose +# Docker Compose Using the already build docker image hosting your own Atuin can be done using the supplied docker-compose file. @@ -54,7 +54,7 @@ Start the services using `docker-compose`: docker-compose up -d ``` -### Using systemd to manage your atuin server +## Using systemd to manage your atuin server The following `systemd` unit file to manage your `docker-compose` managed service: diff --git a/docs/k8s.md b/docs/k8s.md index c4a4d61..c15e838 100644 --- a/docs/k8s.md +++ b/docs/k8s.md @@ -1,4 +1,4 @@ -## Kubernetes +# Kubernetes You could host your own Atuin server using the Kubernetes platform. @@ -167,8 +167,6 @@ spec: Finally, you may want to use a separate namespace for atuin, by creating a [`namespace.yaml`](../k8s/namespaces.yaml) file: -```yaml - ```yaml apiVersion: v1 kind: Namespace diff --git a/docs/zh-CN/README.md b/docs/zh-CN/README.md index 71718f4..7ebaed4 100644 --- a/docs/zh-CN/README.md +++ b/docs/zh-CN/README.md @@ -37,7 +37,7 @@ atuin search --exit 0 --after "yesterday 3pm" make 你可以使用我(ellie)托管的服务器，也可以使用你自己的服务器！或者干脆不使用 sync 功能。所有的历史记录同步都是加密，即使我想，也无法访问你的数据。且我**真的**不想。 -## 特点 +## 功能 - 重新绑定 `up` 和 `ctrl-r` 的全屏历史记录搜索UI界面 - 使用 sqlite 数据库存储 shell 历史记录 @@ -60,7 +60,7 @@ atuin search --exit 0 --after "yesterday 3pm" make - [历史记录统计](./stats.md) - [运行你自己的服务器](./server.md) - [键绑定](./key-binding.md) -- [shell补全](./shell-completions.md) +- [shell 补全](./shell-completions.md) ## 支持的 Shells @@ -87,7 +87,23 @@ atuin register -u -e -p atuin import auto atuin sync ``` - + +### 使用活跃图 + +除了托管 Atuin 服务器外，还有一个服务可以用来生成你的 shell 历史记录使用活跃图！这个功能的灵感来自于 GitHub 的使用活跃图。 + +例如，这是我的： + +![](https://api.atuin.sh/img/ellie.png?token=0722830c382b42777bdb652da5b71efb61d8d387) + +如果你也想要，请在登陆你的同步服务器后，执行 + +``` +curl https://api.atuin.sh/enable -d $(cat ~/.local/share/atuin/session) +``` + +执行结果为你的活跃图 URL 地址。可以共享或嵌入这个 URL 地址，令牌（token）并不是加密的，只是用来防止被枚举攻击。 + ## 仅离线 (不同步) ``` @@ -107,7 +123,9 @@ atuin import auto bash <(curl https://raw.githubusercontent.com/ellie/atuin/main/install.sh) ``` -### 使用cargo +然后可直接看 Shell 插件 + +### 通过 cargo 最好使用 [rustup](https://rustup.rs/) 来设置 Rust 工具链，然后你就可以运行下面的命令: @@ -115,11 +133,15 @@ bash <(curl https://raw.githubusercontent.com/ellie/atuin/main/install.sh) cargo install atuin ``` +然后可直接看 Shell 插件 + ### Homebrew ``` brew install atuin ``` + +然后可直接看 Shell 插件 ### MacPorts @@ -129,6 +151,8 @@ Atuin 也可以在 [MacPorts](https://ports.macports.org/port/atuin/) 中找到 sudo port install atuin ``` +然后可直接看 Shell 插件 + ### Pacman Atuin 在 Arch Linux 的 [社区存储库](https://archlinux.org/packages/community/x86_64/atuin/) 中可用。 @@ -137,6 +161,8 @@ Atuin 在 Arch Linux 的 [社区存储库](https://archlinux.org/packages/commun pacman -S atuin ``` +然后可直接看 Shell 插件 + ### 从源码编译安装 ``` @@ -145,10 +171,11 @@ cd atuin cargo install --path . ``` -## Shell 插件 +然后可直接看 Shell 插件 -安装二进制文件后，需要安装 shell 插件。 -如果你使用的是脚本安装，那么这一切应该都会帮您完成！ +## Shell 插件 + +安装二进制文件后，需要安装 shell 插件。 如果你使用的是脚本安装，那么这一切应该都会帮您完成！ ### zsh @@ -164,14 +191,14 @@ zinit load ellie/atuin ### bash -我们需要设置一些钩子(hooks), 所以首先需要安装 bash-preexec : +我们需要设置一些钩子（hooks）, 所以首先需要安装 bash-preexec : ``` curl https://raw.githubusercontent.com/rcaloras/bash-preexec/master/bash-preexec.sh -o ~/.bash-preexec.sh echo '[[ -f ~/.bash-preexec.sh ]] && source ~/.bash-preexec.sh' >> ~/.bashrc ``` -然后设置Atuin +然后设置 Atuin ``` echo 'eval "$(atuin init bash)"' >> ~/.bashrc @@ -185,12 +212,17 @@ echo 'eval "$(atuin init bash)"' >> ~/.bashrc atuin init fish | source ``` -到 ~/.config/fish/config.fish 文件中的 is-interactive 块中 +到 `~/.config/fish/config.fish` 文件中的 `is-interactive` 块中 + +### Fig + +通过 [Fig](https://fig.io) 可为 zsh， bash 或 fish 一键安装 `atuin` 脚本插件。 + + ## ...这个名字是什么意思? Atuin 以 "The Great A'Tuin" 命名, 这是一只来自 Terry Pratchett 的 Discworld 系列书籍的巨龟。 - [English]: ../../README.md [简体中文]: ./README.md diff --git a/docs/zh-CN/config.md b/docs/zh-CN/config.md index a94b961..7611f88 100644 --- a/docs/zh-CN/config.md +++ b/docs/zh-CN/config.md @@ -89,7 +89,7 @@ key = "~/.atuin-session" ### `search_mode` -使用哪种搜索模式。Atuin 支持 "prefix"（前缀）、"fulltext"（全文） 和 "fuzzy"（模糊）搜索模式。前缀(prefix)搜索语法为 "query\*"，全文(full text)搜索语法为 "\*query\*"，而模糊搜索适用的搜索语法 [如下所述](#fuzzy-search-syntax) 。 +使用哪种搜索模式。Atuin 支持 "prefix"（前缀）、"fulltext"（全文） 和 "fuzzy"（模糊）搜索模式。前缀(prefix)搜索语法为 "query\*"，全文(fulltext)搜索语法为 "\*query\*"，而模糊搜索适用的搜索语法 [如下所述](#fuzzy-search-syntax) 。 默认配置为 "prefix" diff --git a/docs/zh-CN/docker.md b/docs/zh-CN/docker.md new file mode 100644 index 0000000..6470467 --- /dev/null +++ b/docs/zh-CN/docker.md @@ -0,0 +1,90 @@ +# Docker + +Atuin 提供了一个 docker 镜像（image），可以更轻松地将服务器部署为容器（container）。 + +```sh +docker run -d -v "$USER/.config/atuin:/config" ghcr.io/ellie/atuin:latest server start +``` + +# Docker Compose + +使用已有的 docker 镜像（image）来托管你自己的 Atuin，可以使用提供的 docker-compose 文件来完成 + +在 docker-compose.yml 同级目录下创建一个 .env 文件，内容如下: + +``` +ATUIN_DB_USERNAME=atuin +# 填写你的密码 +ATUIN_DB_PASSWORD=really-insecure +``` + +创建 `docker-compose.yml` 文件： + +```yaml +version: '3.5' +services: + atuin: + restart: always + image: ghcr.io/ellie/atuin:main + command: server start + volumes: + - "./config:/config" + links: + - postgresql:db + ports: + - 8888:8888 + environment: + ATUIN_HOST: "0.0.0.0" + ATUIN_OPEN_REGISTRATION: "true" + ATUIN_DB_URI: postgres://$ATUIN_DB_USERNAME:$ATUIN_DB_PASSWORD@db/atuin + postgresql: + image: postgres:14 + restart: unless-stopped + volumes: # 不要删除索引数据库文件的永久存储空间! + - "./database:/var/lib/postgresql/data/" + environment: + POSTGRES_USER: $ATUIN_DB_USERNAME + POSTGRES_PASSWORD: $ATUIN_DB_PASSWORD + POSTGRES_DB: atuin +``` + +使用 `docker-compose` 启动服务： + +```sh +docker-compose up -d +``` + +## 使用 systemd 管理你的 atuin 服务器 + +以下 `systemd` 的配置文件用来管理你的 `docker-compose` 托管服务： + +``` +[Unit] +Description=Docker Compose Atuin Service +Requires=docker.service +After=docker.service + +[Service] +# Where the docker-compose file is located +WorkingDirectory=/srv/atuin-server +ExecStart=/usr/bin/docker-compose up +ExecStop=/usr/bin/docker-compose down +TimeoutStartSec=0 +Restart=on-failure +StartLimitBurst=3 + +[Install] +WantedBy=multi-user.target +``` + +启用服务： + +```sh +systemctl enable --now atuin +``` + +检查服务是否正常运行: + +```sh +systemctl status atuin +``` diff --git a/docs/zh-CN/k8s.md b/docs/zh-CN/k8s.md new file mode 100644 index 0000000..0d9c56e --- /dev/null +++ b/docs/zh-CN/k8s.md @@ -0,0 +1,195 @@ +# Kubernetes + +你可以使用 Kubernetes 来托管你的 Atuin 服务器。 + +为数据库凭证创建 [`secrets.yaml`](../../k8s/secrets.yaml) 文件： + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: atuin-secrets +type: Opaque +stringData: + ATUIN_DB_USERNAME: atuin + ATUIN_DB_PASSWORD: seriously-insecure + ATUIN_HOST: "127.0.0.1" + ATUIN_PORT: "8888" + ATUIN_OPEN_REGISTRATION: "true" + ATUIN_DB_URI: "postgres://atuin:seriously-insecure@localhost/atuin" +immutable: true +``` + +为 Atuin 服务器创建 [`atuin.yaml`](../../k8s/atuin.yaml) 文件： + + +```yaml +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: atuin +spec: + replicas: 1 + selector: + matchLabels: + io.kompose.service: atuin + template: + metadata: + labels: + io.kompose.service: atuin + spec: + containers: + - args: + - server + - start + env: + - name: ATUIN_DB_URI + valueFrom: + secretKeyRef: + name: atuin-secrets + key: ATUIN_DB_URI + optional: false + - name: ATUIN_HOST + value: 0.0.0.0 + - name: ATUIN_PORT + value: "8888" + - name: ATUIN_OPEN_REGISTRATION + value: "true" + image: ghcr.io/ellie/atuin:main + name: atuin + ports: + - containerPort: 8888 + resources: + limits: + cpu: 250m + memory: 1Gi + requests: + cpu: 250m + memory: 1Gi + volumeMounts: + - mountPath: /config + name: atuin-claim0 + - name: postgresql + image: postgres:14 + ports: + - containerPort: 5432 + env: + - name: POSTGRES_DB + value: atuin + - name: POSTGRES_PASSWORD + valueFrom: + secretKeyRef: + name: atuin-secrets + key: ATUIN_DB_PASSWORD + optional: false + - name: POSTGRES_USER + valueFrom: + secretKeyRef: + name: atuin-secrets + key: ATUIN_DB_USERNAME + optional: false + resources: + limits: + cpu: 250m + memory: 1Gi + requests: + cpu: 250m + memory: 1Gi + volumeMounts: + - mountPath: /var/lib/postgresql/data/ + name: database + volumes: + - name: database + persistentVolumeClaim: + claimName: database + - name: atuin-claim0 + persistentVolumeClaim: + claimName: atuin-claim0 +--- +apiVersion: v1 +kind: Service +metadata: + labels: + io.kompose.service: atuin + name: atuin +spec: + type: NodePort + ports: + - name: "8888" + port: 8888 + nodePort: 30530 + selector: + io.kompose.service: atuin +--- +kind: PersistentVolume +apiVersion: v1 +metadata: + name: database-pv + labels: + app: database + type: local +spec: + storageClassName: manual + capacity: + storage: 300Mi + accessModes: + - ReadWriteOnce + hostPath: + path: "/Users/firstname.lastname/.kube/database" +--- +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + labels: + io.kompose.service: database + name: database +spec: + storageClassName: manual + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 300Mi +--- +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + labels: + io.kompose.service: atuin-claim0 + name: atuin-claim0 +spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 10Mi +``` + +最后，你可能想让 atuin 使用单独的命名空间（namespace），创建 [`namespace.yaml`](../../k8s/namespaces.yaml) 文件： + +```yaml +apiVersion: v1 +kind: Namespace +metadata: + name: atuin-namespace + labels: + name: atuin +``` + +在企业级安装部署时，你可能想要数据库内容永久存储在集群中，而不是在主机系统中。在上述配置中，`storageClassName` 配置为 `manual`，主机系统的挂载目录配置为 `/Users/firstname.lastname/.kube/database`，请注意，这些配置将会使得数据库内容存储在 kubernetes 集群外部中。 + +你还应该将 `secrets.yaml` 文件中的 `ATUIN_DB_PASSWORD` 和 `ATUIN_DB_URI` 修改为更安全的加密字符串。 + +Atuin 运行在主机系统的 `30530` 端口上。这是通过 `nodePort` 属性进行陪你的。Kubernetes 有一个严格规则，即不允许暴露小于 30000 的端口号。为了使客户端能够正常工作，你需要在你的 `config.toml` 文件中设置端口号，例如 `sync_address = "http://192.168.1.10:30530"`。 + +使用 `kubectl` 部署 Atuin 服务器： + +```shell + kubectl apply -f ./namespaces.yaml + kubectl apply -n atuin-namespace \ + -f ./secrets.yaml \ + -f ./atuin.yaml +``` + +上面示例同时也位于 atuin 仓库（repository）的 [k8s](../../k8s) 目录下。 diff --git a/docs/zh-CN/key-binding.md b/docs/zh-CN/key-binding.md index ea93032..3e7f2f9 100644 --- a/docs/zh-CN/key-binding.md +++ b/docs/zh-CN/key-binding.md @@ -1,4 +1,4 @@ -# 键绑定 +# 键位绑定 默认情况下， Atuin 将会重新绑定 Ctrl-r 和 `up` 键。如果你不想使用默认绑定，请在调用 `atuin init` 之前设置 ATUIN_NOBIND @@ -35,3 +35,14 @@ eval "$(atuin init bash)" # 绑定到 ctrl-r, 也可以在这里添加任何其他你想要的绑定方式 bind -x '"\C-r": __atuin_history' ``` + +# fish + +``` +set -gx ATUIN_NOBIND "true" +atuin init fish | source + +# 在 normal 和 insert 模式下绑定到 ctrl-r，你也可以在此处添加其他键位绑定 +bind \cr _atuin_search +bind -M insert \cr _atuin_search +``` diff --git a/docs/zh-CN/search.md b/docs/zh-CN/search.md index b99233c..36f4483 100644 --- a/docs/zh-CN/search.md +++ b/docs/zh-CN/search.md @@ -32,6 +32,6 @@ atuin search --exit 0 cargo # 从当前目录中搜索所有在2021年4月1日之前运行且失败的命令。 atuin search --exclude-exit 0 --before 01/04/2021 --cwd . -#搜索所有以 cargo 开头，成功退出且是在昨天下午3点之后运行的命令。 +# 搜索所有以 cargo 开头，成功退出且是在昨天下午3点之后运行的命令。 atuin search --exit 0 --after "yesterday 3pm" cargo ``` diff --git a/docs/zh-CN/server.md b/docs/zh-CN/server.md index 534cb67..4cb39df 100644 --- a/docs/zh-CN/server.md +++ b/docs/zh-CN/server.md @@ -61,94 +61,15 @@ Atuin 服务器应该监听的端口 一个有效的 postgres URI, 用户和历史记录数据将被保存到其中。 -## Docker +### path -提供了一个 docker 镜像（image），可以更轻松地将服务器部署为容器（container）。 +path 指的是给 server 添加的路由前缀。值为空字符串将不会添加路由前缀。 -```sh -docker run -d -v "$USER/.config/atuin:/config" ghcr.io/ellie/atuin:latest server start -``` +默认为 `""` -## Docker Compose +## 容器部署说明 -使用已有的 docker 镜像（image）来托管你自己的 Atuin，可以使用提供的 docker-compose 文件来完成 - -在 `docker-compose.yml` 同级目录下创建一个 `.env` 文件，内容如下: - -``` -ATUIN_DB_USERNAME=atuin -# Choose your own secure password -ATUIN_DB_PASSWORD=really-insecure -``` - -创建一个 `docker-compose.yml` 文件: - -```yaml -version: '3.5' -services: - atuin: - restart: always - image: ghcr.io/ellie/atuin:main - command: server start - volumes: - - "./config:/config" - links: - - postgresql:db - ports: - - 8888:8888 - environment: - ATUIN_HOST: "0.0.0.0" - ATUIN_OPEN_REGISTRATION: "true" - ATUIN_DB_URI: postgres://$ATUIN_DB_USERNAME:$ATUIN_DB_PASSWORD@db/atuin - postgresql: - image: postgres:14 - restart: unless-stopped - volumes: # 不要删除索引数据库文件的永久存储空间! - - "./database:/var/lib/postgresql/data/" - environment: - POSTGRES_USER: $ATUIN_DB_USERNAME - POSTGRES_PASSWORD: $ATUIN_DB_PASSWORD - POSTGRES_DB: atuin -``` - -使用 `docker-compose` 启动服务: - -```sh -docker-compose up -d -``` - -### 使用 systemd 来管理你的 Atuin 服务器 - -以下 `systemd` 单元文件用于管理您的 `docker-compose` 托管服务： - -``` -[Unit] -Description=Docker Compose Atuin Service -Requires=docker.service -After=docker.service - -[Service] -# docker-compose 文件所在的位置 -WorkingDirectory=/srv/atuin-server -ExecStart=/usr/bin/docker-compose up -ExecStop=/usr/bin/docker-compose down -TimeoutStartSec=0 -Restart=on-failure -StartLimitBurst=3 - -[Install] -WantedBy=multi-user.target -``` - -使用以下命令启动并启用服务： - -```sh -systemctl enable --now atuin -``` - -检查它是否运行： - -```sh -systemctl status atuin -``` +你可以在容器中部署自己的 atuin 服务器： +* 有关 docker 配置的示例，请参考 [docker](docker.md)。 +* 有关 kubernetes 配置的示例，请参考 [k8s](k8s.md)。