From bd121f8f94fbea5ce6c814b0039a23a9f6926aa1 Mon Sep 17 00:00:00 2001 From: qwqcode Date: Wed, 18 Sep 2024 23:37:16 +0800 Subject: [PATCH] docs: refine deployment documentation --- README.md | 6 +- README.zh.md | 26 +++-- docs/docs/.vitepress/config/en.ts | 4 +- docs/docs/en/guide/backend/docker.md | 2 +- docs/docs/en/guide/deploy.md | 164 +++++++++++++++------------ docs/docs/zh/guide/backend/docker.md | 2 +- docs/docs/zh/guide/deploy.md | 128 +++++++++++++-------- docs/landing/src/i18n/en.ts | 4 +- docs/landing/src/i18n/zh-CN.ts | 4 +- 9 files changed, 198 insertions(+), 142 deletions(-) diff --git a/README.md b/README.md index cdef4c92..17fc81a0 100644 --- a/README.md +++ b/README.md @@ -65,7 +65,7 @@ Artalk is an intuitive yet feature-rich comment system, ready for immediate depl ## Installation -Deploy with Docker in one step: +Deploy Artalk Server with Docker in one step: ```bash docker run -d \ @@ -79,7 +79,7 @@ docker run -d \ artalk/artalk-go ``` -Integrate Artalk into your webpage: +Integrate Artalk Client into your webpage: @@ -94,6 +94,8 @@ Artalk.init({ +We offer various installation methods, including binary files, go install, and package managers for Linux distributions. + [**Learn More →**](https://artalk.js.org/en/guide/deploy.html) ## For Developers diff --git a/README.zh.md b/README.zh.md index ac79515a..03afce9c 100644 --- a/README.zh.md +++ b/README.zh.md @@ -65,7 +65,7 @@ Artalk 是一款简单易用但功能丰富的评论系统，你可以开箱即 ## 安装 -通过 Docker 一键部署： +通过 Docker 一键部署 Artalk 服务器： ```bash docker run -d \ @@ -79,7 +79,7 @@ docker run -d \ artalk/artalk-go ``` -在网页中引入 Artalk: +在你的网页中引入 Artalk 客户端: @@ -94,37 +94,39 @@ Artalk.init({ +我们提供多种安装方法，包括二进制文件、`go install` 和通过 Linux 发行版的包管理器安装。 + [**了解更多 →**](https://artalk.js.org/zh/guide/deploy.html) -## For Developers +## 参与开发 -Pull requests are welcome! +我们欢迎你的 Pull Request！ -See [Development](https://artalk.js.org/zh/develop/) and [Contributing](./CONTRIBUTING.md) for information on working with the codebase, getting a local development setup, and contributing changes. +有关如何使用代码库、设置本地开发环境和贡献更改的信息，请参阅 [开发文档](https://artalk.js.org/zh/develop/) 和 [贡献指南](./CONTRIBUTING.md)。 -## Contributors +## 贡献者们 -Your contributions enrich the open-source community, fostering learning, inspiration, and innovation. We deeply value your involvement. Thank you for being a vital part of our community! 🥰 +你的贡献丰富了开源社区，促进了学习、灵感和创新。我们非常重视你的参与。感谢你成为我们社区的重要一员！🥰 [![](https://contrib.rocks/image?repo=ArtalkJS/Artalk)](https://github.com/ArtalkJS/Artalk/graphs/contributors) -## Supporters +## 支持者们 [![Stargazers repo roster for @ArtalkJS/Artalk](https://reporoster.com/stars/ArtalkJS/Artalk)](https://github.com/ArtalkJS/Artalk/stargazers) -## Repobeats Analytics +## Repobeats 分析 ![Alt](https://repobeats.axiom.co/api/embed/a9fc9191ac561bc5a8ee2cddc81e635ecaebafb6.svg 'Repobeats analytics image') -## Stargazers over time +## Star 趋势 ArtalkJS%2FArtalk | Trendshift [![Stargazers over time](https://starchart.cc/ArtalkJS/Artalk.svg)](https://starchart.cc/ArtalkJS/Artalk) -## License +## 开源许可协议 -[MIT](./LICENSE) +[MIT](./LICENSE) (麻省理工学院许可证) [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2FArtalkJS%2FArtalk.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2FArtalkJS%2FArtalk?ref=badge_shield) diff --git a/docs/docs/.vitepress/config/en.ts b/docs/docs/.vitepress/config/en.ts index 59e80497..336a216c 100644 --- a/docs/docs/.vitepress/config/en.ts +++ b/docs/docs/.vitepress/config/en.ts @@ -11,8 +11,8 @@ export const en = defineConfig({ text: 'Quick Start', collapsed: false, items: [ - { text: 'Project Introduction', link: '/en/guide/intro.md' }, - { text: 'Program Deployment', link: '/en/guide/deploy.md' }, + { text: 'Introduction', link: '/en/guide/intro.md' }, + { text: 'Getting Started', link: '/en/guide/deploy.md' }, { text: 'Data Migration', link: '/en/guide/transfer.md' }, ], }, diff --git a/docs/docs/en/guide/backend/docker.md b/docs/docs/en/guide/backend/docker.md index 1f1769eb..94a8a2e6 100644 --- a/docs/docs/en/guide/backend/docker.md +++ b/docs/docs/en/guide/backend/docker.md @@ -98,4 +98,4 @@ docker exec -it artalk bash ## Multi-Platform Compatibility -The Docker image currently only provides builds for x86 and arm64 architectures. For more platform architectures, please download the binary build and deploy it using the [Ordinary Deployment](../deploy.md#普通方式部署) method. +The Docker image currently only provides builds for x86 and arm64 architectures. For more platform architectures, please download the binary build and deploy it using the [Binary Deployment](../deploy.md#binary) method. diff --git a/docs/docs/en/guide/deploy.md b/docs/docs/en/guide/deploy.md index 26b23807..17fed12f 100644 --- a/docs/docs/en/guide/deploy.md +++ b/docs/docs/en/guide/deploy.md @@ -1,8 +1,14 @@ -# 📦 Program Deployment +# 📦 Getting Started -## Docker Deployment +This guide will help you deploy Artalk on your server. Once deployed, you can integrate the Artalk client into your website or blog to enable comment functionality. -It is recommended to deploy using Docker. Pre-install the [Docker Engine](https://docs.docker.com/engine/install/) and execute the command to create the container: +## Docker + +Here is a simple guide for deploying the Artalk **Server** and **Client**. + +### Launch Server + +It is recommended to use Docker for deployment. Pre-install the [Docker Engine](https://docs.docker.com/engine/install/) and create a working directory, then run the command to launch a container in the background: ```bash docker run -d \ @@ -16,17 +22,19 @@ docker run -d \ artalk/artalk-go ``` -Execute the command to create an admin account: +(Tip: We also provide a [Docker Compose](#docker-compose) configuration file). + +Run the command to create an admin account: ```bash docker exec -it artalk artalk admin ``` -Enter `http://artalk.example.com:8080` in your browser to access the Artalk admin login interface. +Enter `http://artalk.example.com:8080` in your browser to access the Artalk Dashboard. -Incorporate the embedded front-end JS and CSS resources of the Artalk program into the webpage and initialize Artalk: +### Integrate Client - +Import the embedded client JS and CSS resources from the Artalk server to your webpage and initialize the Artalk client: ```html @@ -42,25 +50,24 @@ Artalk.init({ el: '#Comments', // Selector of the bound element pageKey: '/post/1', // Permalink pageTitle: 'About Introducing Artalk', // Page title (leave blank to auto-fetch) - server: 'http://artalk.example.com:8080', // Backend address - site: 'Artalk Blog', // Your site name + server: 'http://artalk.example.com:8080', // Artalk server address + site: 'Artalk Blog', // Your site name }) ``` - -Enter the admin username and email in the comment box, and the "Console" button will appear at the bottom right of the comment box. +Enter the admin username and email in the comment box, and the "Dashboard" button will appear at the bottom right of the comment box. -In the console, you can [configure the comment system](./backend/config.md) according to your preferences or [migrate comments to Artalk](./transfer.md). +In the Dashboard, you can [configure the comment system](./backend/config.md) to your liking or [migrate comments to Artalk](./transfer.md). -🥳 You have successfully completed the Artalk deployment! +🥳 You have successfully deployed Artalk! -## Standard Deployment +## Binary 1. Download the program package from [GitHub Release](https://github.com/ArtalkJS/Artalk/releases) 2. Extract it with `tar -zxvf artalk_version_system_architecture.tar.gz` 3. Run `./artalk server` -4. Configure +4. Configure and initialize the client on your webpage: ```js Artalk.init({ server: 'http://artalk.example.com:23366' }) @@ -72,9 +79,47 @@ Advanced operations: - [Reverse Proxy (Caddy, Nginx, Apache)](./backend/reverse-proxy.md) - [Self-compile (Build from the latest code)](https://github.com/ArtalkJS/Artalk/blob/master/CONTRIBUTING.md) -## Compose Deployment +## Go Module + +If you have the Golang toolchain installed, you can run the following commands to compile and install the latest version of Artalk: + +```bash +go install github.com/artalkjs/artalk/v2@latest +``` + +Then run the server: + +```bash +artalk server +``` + +The client integration steps are [here](#integrate-client). + +## Linux Distributions + +**Arch Linux (AUR)**: + +```bash +paru -S artalk +``` + +**NixOS**: + +```bash +nix-env -iA nixpkgs.artalk +``` + +**Termux**: + +```bash +pkg install artalk +``` + +[![Packaging status](https://repology.org/badge/vertical-allrepos/artalk.svg)](https://repology.org/project/artalk/versions) -**compose.yaml** +## Docker Compose + +Create a working directory and edit the `docker-compose.yml` file: ```yaml version: '3.8' @@ -94,12 +139,14 @@ services: - ATK_SITE_URL=https://your_domain ``` -Create the container: +Start the container to launch Artalk server: ```bash docker-compose up -d ``` +The client integration steps are [here](#integrate-client). + ::: details Common Compose Commands ```bash @@ -112,40 +159,48 @@ docker-compose exec artalk bash # Enter the container ::: -Refer to the documentation: [Docker](./backend/docker.md) / [Environment Variables](./env.md) +More information: [Docker](./backend/docker.md) / [Environment Variables](./env.md) -## Linux Distributions +## Client Projects (Node.js) -**Arch Linux (AUR)**: +Install Artalk via npm: ```bash -paru -S artalk +npm install artalk ``` -**NixOS**: - -```bash -nix-env -iA nixpkgs.artalk -``` +Import Artalk in your web project: -**Termux**: +```js +import 'artalk/dist/Artalk.css' +import Artalk from 'artalk' -```bash -pkg install artalk +const artalk = Artalk.init({ + el: '#Comments', // Selector of the bound element + pageKey: '/post/1', // Permalink + pageTitle: 'About Introducing Artalk', // Page title (leave blank to auto-fetch) + server: 'http://artalk.example.com:8080', // Artalk server address + site: 'Artalk Blog', // Your site name +}) ``` -[![Packaging status](https://repology.org/badge/vertical-allrepos/artalk.svg)](https://repology.org/project/artalk/versions) +For more references: -## CDN Resources +- [Import to Blog Documentation](../develop/import-blog.md) +- [Import to Frameworks Documentation](../develop/import-framework.md) +- [Client API Reference](../develop/fe-api.md) +- [Client Configuration](./frontend/config.md) + +## Client CDN Resources ::: tip Latest Version of Artalk -The current latest version number of the Artalk front-end is: **:ArtalkVersion:** +The current latest version number of the Artalk client is: **:ArtalkVersion:** -To upgrade the front-end, simply replace the numeric part of the version number in the URL. +To upgrade the client, replace the numeric part of the version number in the URL. ::: -The back-end program of Artalk integrates front-end JS and CSS files. Please pay attention to version compatibility when using public CDN resources. +The Artalk server had embedded the client resources. Ensure version compatibility when using public CDN resources. **CDNJS** @@ -154,11 +209,6 @@ The back-end program of Artalk integrates front-end JS and CSS files. Please pay > ::: details View More -**SUSTech Mirrors (Domestic)** - -> -> -> **UNPKG** @@ -174,40 +224,14 @@ The back-end program of Artalk integrates front-end JS and CSS files. Please pay ::: -## Node Projects - -Install Artalk: - -```bash -npm install artalk -``` - -Import Artalk: - -```js -import 'artalk/dist/Artalk.css' -import Artalk from 'artalk' - -Artalk.init({ - // ... -}) -``` - -For more references: - -- [Embedding in Blog Documentation](../develop/import-blog.md) -- [Embedding in Framework Documentation](../develop/import-framework.md) -- [Front-end Configuration](./frontend/config.md) -- [Front-end API](../develop/fe-api.md) - -## Data Import +## Data Migration -Import data from other comment systems: [Data Migration](./transfer.md) +Import data from other comment systems: [Data Migration](./transfer.md). ## ArtalkLite -Consider the lightweight version [ArtalkLite](./frontend/artalk-lite.md): smaller and more streamlined. +ArtalkLite is a lightweight version of the Artalk client. See: [ArtalkLite](./frontend/artalk-lite.md). ## Development Environment -Refer to: [Developer Guide](https://github.com/ArtalkJS/Artalk/blob/master/CONTRIBUTING.md) +Please refer to: [Developer Guide](https://github.com/ArtalkJS/Artalk/blob/master/CONTRIBUTING.md). diff --git a/docs/docs/zh/guide/backend/docker.md b/docs/docs/zh/guide/backend/docker.md index e3a69db3..68a4b371 100644 --- a/docs/docs/zh/guide/backend/docker.md +++ b/docs/docs/zh/guide/backend/docker.md @@ -98,4 +98,4 @@ docker exec -it artalk bash ## 多平台兼容性 -Docker 镜像暂仅提供 x86、arm64 的镜像构建，如需更多平台架构版本，请下载 [二进制构建部署](../deploy.md#普通方式部署)。 +Docker 镜像暂仅提供 x86、arm64 的镜像构建，如需更多平台架构版本，请下载 [二进制构建部署](../deploy.md#二进制文件)。 diff --git a/docs/docs/zh/guide/deploy.md b/docs/docs/zh/guide/deploy.md index 6674eb8b..40d097e9 100644 --- a/docs/docs/zh/guide/deploy.md +++ b/docs/docs/zh/guide/deploy.md @@ -1,8 +1,14 @@ # 📦 程序部署 -## Docker 部署 +该指南将帮助你在服务器上部署 Artalk。之后，你可以将 Artalk 客户端集成到你的网站或博客中，让用户能够在你的网站上畅所欲言。 -推荐使用 Docker 部署，需预先安装 [Docker 引擎](https://docs.docker.com/engine/install/)，执行命令创建容器： +## Docker + +以下是一个简单的 Artalk **服务器** 和 **客户端** 部署示例。 + +### 启动服务器 + +推荐使用 Docker 部署，预先安装 [Docker 引擎](https://docs.docker.com/engine/install/) 并创建一个工作目录，然后执行命令在后台启动容器： ```bash docker run -d \ @@ -16,6 +22,8 @@ docker run -d \ artalk/artalk-go ``` +（注意：我们也提供了 [Docker Compose](#docker-compose) 的配置文件）。 + 执行命令创建管理员账户： ```bash @@ -24,6 +32,8 @@ docker exec -it artalk artalk admin 浏览器输入 `http://artalk.example.com:8080` 进入 Artalk 后台登录界面。 +### 集成客户端 + 在网页中引入 Artalk 程序内嵌的的前端 JS 和 CSS 资源并初始化 Artalk： @@ -55,12 +65,12 @@ Artalk.init({ 🥳 你已成功完成 Artalk 部署！ -## 普通方式部署 +## 二进制文件 1. [GitHub Release](https://github.com/ArtalkJS/Artalk/releases) 下载程序压缩包 2. 解压 `tar -zxvf artalk_版本号_系统_架构.tar.gz` 3. 运行 `./artalk server` -4. 配置 +4. 在你的网页中配置和初始化 Artalk 客户端： ```js Artalk.init({ server: 'http://artalk.example.com:23366' }) @@ -72,9 +82,47 @@ Artalk.init({ - [反向代理 (Caddy, Nginx, Apache)](./backend/reverse-proxy.md) - [自编译 (通过最新代码构建)](../develop/contributing.md) -## Compose 部署 +## Go 模块 + +如果你已经安装了 Golang 工具链，可以运行以下命令来编译和安装最新版本的 Artalk： + +```bash +go install github.com/artalkjs/artalk/v2@latest +``` + +然后运行服务器： + +```bash +artalk server +``` + +客户端集成步骤详见[此处](#集成客户端)。 -**compose.yaml** +## Linux 发行版 + +**Arch Linux (AUR)**： + +```bash +paru -S artalk +``` + +**NixOS**： + +```bash +nix-env -iA nixpkgs.artalk +``` + +**Termux**： + +```bash +pkg install artalk +``` + +[![Packaging status](https://repology.org/badge/vertical-allrepos/artalk.svg)](https://repology.org/project/artalk/versions) + +## Docker Compose + +创建一个工作目录，并编辑 `docker-compose.yml` 文件： ```yaml version: '3.8' @@ -94,12 +142,14 @@ services: - ATK_SITE_URL=https://your_domain ``` -创建容器： +创建容器运行 Artalk 服务器： ```bash docker-compose up -d ``` +客户端集成步骤详见[此处](#集成客户端)。 + ::: details Compose 常用命令 ```bash @@ -112,31 +162,35 @@ docker-compose exec artalk bash # 进入容器 ::: -参考文档：[Docker](./backend/docker.md) / [环境变量](./env.md) +更多信息：[Docker](./backend/docker.md) / [环境变量](./env.md) -## Linux 发行版 +## 前端项目 (Node.js) -**Arch Linux (AUR)**： +通过 NPM 安装 Artalk： ```bash -paru -S artalk +npm install artalk ``` -**NixOS**： - -```bash -nix-env -iA nixpkgs.artalk -``` +在你的 Web 项目中引入 Artalk： -**Termux**： +```js +import 'artalk/dist/Artalk.css' +import Artalk from 'artalk' -```bash -pkg install artalk +Artalk.init({ + // ... +}) ``` -[![Packaging status](https://repology.org/badge/vertical-allrepos/artalk.svg)](https://repology.org/project/artalk/versions) +更多参考： -## CDN 资源 +- [置入博客文档](../develop/import-blog.md) +- [置入框架文档](../develop/import-framework.md) +- [前端 API](../develop/fe-api.md) +- [前端配置](./frontend/config.md) + +## 前端 CDN 资源 ::: tip Artalk 最新版本 @@ -174,40 +228,14 @@ Artalk 后端程序内嵌了前端 JS、CSS 文件，使用公共 CDN 资源请 ::: -## Node 项目 - -安装 Artalk： - -```bash -npm install artalk -``` - -引入 Artalk： - -```js -import 'artalk/dist/Artalk.css' -import Artalk from 'artalk' - -Artalk.init({ - // ... -}) -``` - -更多参考： - -- [置入博客文档](../develop/import-blog.md) -- [置入框架文档](../develop/import-framework.md) -- [前端配置](./frontend/config.md) -- [前端 API](../develop/fe-api.md) - ## 数据导入 -从其他评论系统导入数据：[数据迁移](./transfer.md) +从其他评论系统导入数据：[数据迁移](./transfer.md)。 ## ArtalkLite -可选择精简版 [ArtalkLite](./frontend/artalk-lite.md)：体积更小、更简约。 +ArtalkLite 是一个轻量级的精简 Artalk 客户端，体积更小、更简约。查看：[ArtalkLite](./frontend/artalk-lite.md)。 ## 开发环境 -可参考：[开发者指南](https://github.com/ArtalkJS/Artalk/blob/master/CONTRIBUTING.md) +请参考：[开发者指南](https://github.com/ArtalkJS/Artalk/blob/master/CONTRIBUTING.md)。 diff --git a/docs/landing/src/i18n/en.ts b/docs/landing/src/i18n/en.ts index d1d5d811..e0e717fe 100644 --- a/docs/landing/src/i18n/en.ts +++ b/docs/landing/src/i18n/en.ts @@ -21,10 +21,10 @@ export const en = { feature_swift_self_compile: 'Planning to compile from source?', deploy_bin: 'BINARY', deploy_bin_sub: 'DEPLOYMENT', - deploy_bin_link: 'https://artalk.js.org/en/guide/deploy.html#standard-deployment', + deploy_bin_link: 'https://artalk.js.org/en/guide/deploy.html#binary', deploy_docker: 'DOCKER', deploy_docker_sub: 'DEPLOYMENT', - deploy_docker_link: 'https://artalk.js.org/en/guide/deploy.html#docker-deployment', + deploy_docker_link: 'https://artalk.js.org/en/guide/deploy.html#docker', docker_hub_link: 'https://hub.docker.com/r/artalk/artalk-go', self_compile_guide_link: 'https://github.com/ArtalkJS/Artalk/blob/master/CONTRIBUTING.md', learn_more: 'Learn More', diff --git a/docs/landing/src/i18n/zh-CN.ts b/docs/landing/src/i18n/zh-CN.ts index b003ed3d..2a56cfca 100644 --- a/docs/landing/src/i18n/zh-CN.ts +++ b/docs/landing/src/i18n/zh-CN.ts @@ -21,10 +21,10 @@ export const zhCN: MessageSchema = { feature_swift_self_compile: '打算使用代码自编译？', deploy_bin: '二进制', deploy_bin_sub: '文件部署', - deploy_bin_link: 'https://artalk.js.org/zh/guide/deploy.html#普通方式部署', + deploy_bin_link: 'https://artalk.js.org/zh/guide/deploy.html#二进制文件', deploy_docker: 'Docker', deploy_docker_sub: '镜像部署', - deploy_docker_link: 'https://artalk.js.org/zh/guide/deploy.html#docker-部署', + deploy_docker_link: 'https://artalk.js.org/zh/guide/deploy.html#docker', docker_hub_link: 'https://hub.docker.com/r/artalk/artalk-go', self_compile_guide_link: 'https://artalk.js.org/zh/develop/contributing.html', learn_more: '了解更多',