update zh-CN docs (#539)

* update zh-CN docs * update zh-CN docs * update zh-CN docs * update zh-CN docs
2024-11-22 08:13:57 +01:00 · 2022-10-08 11:36:49 +08:00 · 2022-10-08 11:36:49 +08:00 · 02049bf68d
commit 02049bf68d
parent 5725f4b40b
11 changed files with 357 additions and 108 deletions
--- 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
--- 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).

--- 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:

--- 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
--- 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 <USERNAME> -e <EMAIL> -p <PASSWORD>
 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）并<i>不是</i>加密的，只是用来防止被枚举攻击。
+
 ## 仅离线 (不同步)
  
 ```
@ -107,7 +123,9 @@ atuin import auto
 bash <(curl https://raw.githubusercontent.com/ellie/atuin/main/install.sh)
 ```

-### 使用cargo
+然后可直接看 <a href="#shell-plugin">Shell 插件</a>
+
+### 通过 cargo

 最好使用 [rustup](https://rustup.rs/) 来设置 Rust 工具链，然后你就可以运行下面的命令:

@ -115,11 +133,15 @@ bash <(curl https://raw.githubusercontent.com/ellie/atuin/main/install.sh)
 cargo install atuin
 ```

+然后可直接看 <a href="#shell-plugin">Shell 插件</a>
+
 ### Homebrew

 ```
 brew install atuin
 ```
+
+然后可直接看 <a href="#shell-plugin">Shell 插件</a>
  
 ### MacPorts

@ -129,6 +151,8 @@ Atuin 也可以在 [MacPorts](https://ports.macports.org/port/atuin/) 中找到
 sudo port install atuin
 ```

+然后可直接看 <a href="#shell-plugin">Shell 插件</a>
+
 ### 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
 ```

+然后可直接看 <a href="#shell-plugin">Shell 插件</a>
+
 ### 从源码编译安装

 ```
@ -145,10 +171,11 @@ cd atuin
 cargo install --path .
 ```

-## Shell 插件
+然后可直接看 <a href="#shell-plugin">Shell 插件</a>

-安装二进制文件后，需要安装 shell 插件。 
-如果你使用的是脚本安装，那么这一切应该都会帮您完成！
+## <a id="shell-plugin">Shell 插件</a>
+
+安装二进制文件后，需要安装 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` 脚本插件。
+
+<a href="https://fig.io/plugins/other/atuin" target="_blank"><img src="https://fig.io/badges/install-with-fig.svg" /></a>

 ## ...这个名字是什么意思?

 Atuin 以 "The Great A'Tuin" 命名, 这是一只来自 Terry Pratchett 的 Discworld 系列书籍的巨龟。

-
 [English]: ../../README.md
 [简体中文]: ./README.md
--- 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"

--- a/docs/zh-CN/docker.md
+++ 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
+```
--- a/docs/zh-CN/k8s.md
+++ 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 集群<i>外部</i>中。
+
+你还应该将 `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) 目录下。
--- a/docs/zh-CN/key-binding.md
+++ b/docs/zh-CN/key-binding.md
@ -1,4 +1,4 @@
-# 键绑定
+# 键位绑定

 默认情况下， Atuin 将会重新绑定 <kbd>Ctrl-r</kbd> 和 `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
+```
--- 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
 ```
--- 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)。