Merge pull request #467 from carbon-bond/new-doc

新增給架站人看的文件
carbon-bond · Feb 26, 2023 · 527d79c · 527d79c
2 parents 5d9dbfa + ff25a6c
commit 527d79c
Show file tree

Hide file tree

Showing 31 changed files with 175 additions and 20 deletions.
diff --git a/README.md b/README.md
@@ -32,7 +32,7 @@
 - 支援 Markdown 標記語言
     - 也考慮設計碳鍵自己的標記語言
 
-更多細節詳見[碳鍵指南](./doc/指南.md)。
+更多細節詳見[碳鍵文件](https://docs.carbonbond.cc)。
 
 ## 建置
 - 後端：使用 Rust 語言開發。
@@ -52,4 +52,4 @@
     + `yarn dev` 啓動前端伺服器，支援熱重載
     + `yarn lint` 檢查風格
 
-更詳細的步驟請見 [快速開始](./doc/快速開始.md)。
+更詳細的步驟請見 [快速開始](https://docs.carbonbond.cc/快速開始.html)。
diff --git a/api-service/config/carbonbond.toml b/api-service/config/carbonbond.toml
@@ -30,9 +30,10 @@ signup_whitelist = []
     # type = Mailgun
     # mailgun_api_key = "API_KEY"
 
-    # 若 type = "SMTP" ， 需額外提供 smtp_username, smtp_password
+    # 若 type = "SMTP" ， 需額外提供 smtp_server, smtp_username, smtp_password
     # type = "SMTP"
-    # smtp_username = "[email protected]" # username 是一個完整的電郵地址
+    # smtp_server = "smtp.provider.com"
+    # smtp_username = "[email protected]" # username 是一個完整的電郵地址
     # smtp_password = "my_smtp_password"
 
 [database]

diff --git a/api-service/src/config/config.rs b/api-service/src/config/config.rs
@@ -38,6 +38,7 @@ pub struct ServerConfig {
 pub enum EmailDriver {
     Log,
     SMTP {
+        smtp_server: String,
         smtp_username: String,
         smtp_password: String,
     },

diff --git a/api-service/src/email/mod.rs b/api-service/src/email/mod.rs
@@ -39,6 +39,7 @@ async fn send_html_email(receiver: &str, subject: &str, html_content: String) ->
             .await
         }
         EmailDriver::SMTP {
+            smtp_server,
             smtp_username,
             smtp_password,
         } => {
@@ -47,6 +48,7 @@ async fn send_html_email(receiver: &str, subject: &str, html_content: String) ->
                 receiver,
                 subject,
                 html_content,
+                smtp_server,
                 smtp_username,
                 smtp_password,
             )

diff --git a/api-service/src/email/smtp.rs b/api-service/src/email/smtp.rs
@@ -9,6 +9,7 @@ pub async fn send_via_smtp(
     receiver: &str,
     subject: &str,
     html_content: String,
+    smtp_server: &str,
     smtp_username: &str,
     smtp_password: &str,
 ) -> Fallible<()> {
@@ -23,7 +24,7 @@ pub async fn send_via_smtp(
     let creds = Credentials::new(smtp_username.to_owned(), smtp_password.to_owned());
 
     let mailer: AsyncSmtpTransport<Tokio1Executor> =
-        AsyncSmtpTransport::<Tokio1Executor>::relay("smtp.mailgun.org")
+        AsyncSmtpTransport::<Tokio1Executor>::relay(smtp_server)
             .unwrap()
             .credentials(creds)
             .build();

diff --git a/docs-website/docs/.vitepress/config.ts b/docs-website/docs/.vitepress/config.ts
@@ -1,36 +1,61 @@
 export default {
   title: '碳鍵',
-  description: '戰爭，一觸即發',
+  description: '次世代筆戰平台',
+  head: [
+    ['link', { rel: 'icon', type: 'image/svg+xml', href: '/icon.svg' }],
+  ],
   themeConfig: {
 	  logo: '/icon.svg',
+    socialLinks: [
+      {
+        icon: 'github',
+        link: 'https://github.com/carbon-bond/carbonbond',
+      }
+    ],
     nav: [
       { text: '主站', link: 'https://carbonbond.cc' }
     ],
 	  sidebar: [
 		  {
-        text: '介紹',
+        text: '基礎',
+        items: [
+          { text: '碳鍵是什麼？', link: '/基礎/碳鍵是什麼.html' },
+          { text: '安裝', link: '/基礎/安裝.html' },
+          { text: '電郵設定', link: '/基礎/電郵設定.html' },
+          { text: '設定檔一覽', link: '/基礎/設定檔一覽.html' }
+        ]
+      },
+		  {
+        text: '進階',
         items: [
-          { text: '碳鍵是什麼？', link: '/概述/碳鍵是什麼.html' }
+          { text: '架構', link: '/進階/架構.html' },
+          { text: 'HTTPS', link: '/進階/HTTPS.html' }
         ]
       },
 		  {
         text: '開發',
         items: [
-          { text: '碳鍵是什麼？', link: '/概述/碳鍵是什麼.html' }
+          { text: '環境設定', link: '/開發/環境設定.html' },
+          { text: '本地編譯、執行', link: '/開發/本地運行.html' }
         ]
       },
 		  {
         text: '早期文件',
         items: [
-          { text: '起源', link: '/起源.html' },
-          { text: '快速開始', link: '/快速開始.html' },
-          { text: 'docker啓動', link: '/docker啓動.html' },
-          { text: 'rust 設置', link: '/rust設置.html' },
-          { text: '前端設置', link: '/前端設置.html' },
-          { text: '資料庫設置', link: '/資料庫設置.html' },
+          { text: '起源', link: '/早期文件/起源.html' },
+          { text: '快速開始', link: '/早期文件/快速開始.html' },
+          { text: 'docker啓動', link: '/早期文件/docker啓動.html' },
+          { text: 'rust 設置', link: '/早期文件/rust設置.html' },
+          { text: '前端設置', link: '/早期文件/前端設置.html' },
+          { text: '資料庫設置', link: '/早期文件/資料庫設置.html' },
         ]
       }
 	  ]
   },
-  ignoreDeadLinks: 'localhostLinks'
+  ignoreDeadLinks: 'localhostLinks',
+  markdown: {
+    config: (md) => {
+      md.use(require('markdown-it-footnote'));
+    }
+  }
 }
diff --git a/docs-website/docs/index.md b/docs-website/docs/index.md
@@ -15,7 +15,7 @@ hero:
   actions:
     - theme: brand
       text: 出發
-      link: /概述/碳鍵是什麼
+      link: /基礎/碳鍵是什麼
     - theme: alt
       text: 源碼
       link: https://github.com/carbon-bond/carbonbond

diff --git a/docs-website/docs/基礎/安裝.md b/docs-website/docs/基礎/安裝.md
@@ -0,0 +1,34 @@
+# 安裝
+
+碳鍵依賴多項軟體跟開發工具，從頭編譯、並架設 Nginx, Redis 等等軟體會花上不少時間。
+
+所幸，碳鍵官方提供了 docker 映像檔，能夠簡化架設流程。您僅需要先在你的機器上安裝 Docker 就可以了。
+
+## 安裝 Docker
+
+Linux 用戶可根據 Docker 官網的指示安裝 [Docker Engine](https://docs.docker.com/engine/install/)，Mac 與 Windows 用戶則適用 [Docker Desktop](https://docs.docker.com/desktop/)。
+
+## 啓動碳鍵
+
+1. 下載 carbonbond 原始碼。
+```
+git clone https://github.com/carbon-bond/carbonbond
+cd carbonbond
+```
+2. 建立 carbonbond.release.toml 文件，請先直接複製原始碼中提供的 carbonbond.docker.toml。
+```
+cp api-service/config/carbonbond.docker.toml api-service/config/carbonbond.release.toml
+```
+
+3. 啓動。
+```
+cd deploy
+sudo docker compose up
+```
+`docker compose` 會自動下載並執行最新的碳鍵映像檔，若您在終端看到
+
+> 靜候於 http://0.0.0.0:8080
+
+代表碳鍵 API 伺服器已經佈署成功，用瀏覽器打開 http://localhost [^1]，若您看到了論壇界面，恭喜您已經邁出了重大的一步，但您還需要一些額外設定才能開放給社羣使用。請看下一章[電郵設定](./%E9%9B%BB%E9%83%B5%E8%A8%AD%E5%AE%9A.md)。
+
+[^1]: localhost 的 80 埠口由一個 Nginx 容器負責監聽，而`靜候於 http://0.0.0.0:8080`這段文字是碳鍵的 API 伺服器打印出來的。Nginx 收到 API 請求時，會把請求反向代理給 8080 埠口。
diff --git a/docs-website/docs/基礎/碳鍵是什麼.md b/docs-website/docs/基礎/碳鍵是什麼.md
@@ -0,0 +1,3 @@
+# 碳鍵是什麼？
+
+撰寫中
diff --git a/docs-website/docs/基礎/設定檔一覽.md b/docs-website/docs/基礎/設定檔一覽.md
diff --git a/docs-website/docs/基礎/電郵設定.md b/docs-website/docs/基礎/電郵設定.md
@@ -0,0 +1,47 @@
+# 電郵設定
+
+按照[上一章節](./%E5%AE%89%E8%A3%9D.md)以 docker 啓動碳鍵之後，點擊網頁右上方的註冊按鈕，輸入測試郵件 `[email protected]` 並送出。您會在 `docker compose` 的日誌(log)中看到驗證信的內容：
+
+```
+寄件者：碳鍵 <[email protected]>
+收件者：[email protected]
+主旨：歡迎您註冊碳鍵
+內文：<html> <h1>歡迎加入碳鍵！</h1> <p>點選以下連結，一起嘴爆那些笨蛋吧！</p> <a href="http://localhost/app/signup/HlpGrzuxiXlofCWSelJ1Qa04REJtfPWM">http://localhost/app/signup/HlpGrzuxiXlofCWSelJ1Qa04REJtfPWM</a> <br/> </html>
+```
+
+然而，並不會真的有一封信送到 `[email protected]`。那是因爲設定檔 `api-service/config/carbonbond.release.toml` 中，`email.driver` 的 `type` 被預設爲 `Log`。在此設定下， 電郵內容不會寄發，而是直接打印到日誌。想要真正寄發郵件到網路上，您需要設定 SMTP ，或是使用 Mailgun 的金鑰。
+
+## SMTP
+
+SMTP（簡單郵遞傳送協定） 是現今全球通用的電郵傳送標準，碳鍵支援使用 SMTP 伺服器的帳號密碼來寄送信件。
+
+全球最大的電郵供應商 [Gmail](https://gmail.com) 提供了免費的 SMTP 服務，以下僅以 Gmail 爲例，但您可將設定套用到其他提供 SMTP 服務的電郵供應商，或是自架的 SMTP 伺服器。
+
+1. 註冊並登入 Google 帳戶
+2. [ [Google 帳戶](https://myaccount.google.com) => 安全性 => 登入 Google => 應用程式密碼 ] 取得密碼。
+
+設定 `carbonbond.release.toml` 的 `email.driver` 如下
+``` toml
+[email.driver]
+type = "SMTP
+smtp_server = "smtp.gmail.com"
+smtp_username = <帳號名@gmail.com>
+smtp_password = <應用程式密碼>
+```
+
+## Mailgun
+Mailgun 是知名的企業電郵服務商，註冊後，該網站提供免費（有額度限制）的電郵寄送服務，除了可以使用上一小節的講述的 SMTP 帳密，Maigun 還提供了 API key 可以讓您在無需帳號密碼的情況下寄發郵件。
+
+首先，註冊 Mailgun 並按照 [Mailgun 的官方文件](https://documentation.mailgun.com/en/latest/user_manual.html)驗證您持有的網域。如果您尚未購買網域，也可以用 Mailgun 提供的測試網域。您可以在[這裏](https://app.mailgun.com/app/sending/domains)查看您可以使用的網域。
+
+若您已註冊好 Mailgun ，可以在[這裏](https://app.mailgun.com/app/account/security/api_keys)查看(Private) API key。
+
+
+設定 `carbonbond.release.toml` 的 `email.driver` 如下
+``` toml
+domail = "您的域名"
+from = "寄件人稱呼 <noreply@您的域名>"
+[email.driver]
+type = "Mailgun
+mailgun_api_key = <API_KEY>
+```
diff --git a/docs-website/docs/docker啓動.md → docs-website/docs/早期文件/docker啓動.md b/docs-website/docs/docker啓動.md → docs-website/docs/早期文件/docker啓動.md
@@ -20,14 +20,14 @@ cp carbonbond.docker.toml carbonbond.release.toml
 ```sh
 cd deploy
 sh build.sh
-docker-compose build
+docker compose build
 ```
 
 4. 啓動 docker
 
 ```sh
 cd deploy
-docker-compose up
+docker compose up
 ```
 
 需先關閉本地端的 postgresql ，否則埠口會撞到
diff --git a/docs-website/docs/img/ptt討論串.png → docs-website/docs/早期文件/img/ptt討論串.png b/docs-website/docs/img/ptt討論串.png → docs-website/docs/早期文件/img/ptt討論串.png
diff --git a/docs-website/docs/img/ptt課程評價_1.png → docs-website/docs/早期文件/img/ptt課程評價_1.png b/docs-website/docs/img/ptt課程評價_1.png → docs-website/docs/早期文件/img/ptt課程評價_1.png
diff --git a/docs-website/docs/img/ptt課程評價_2.png → docs-website/docs/早期文件/img/ptt課程評價_2.png b/docs-website/docs/img/ptt課程評價_2.png → docs-website/docs/早期文件/img/ptt課程評價_2.png
diff --git a/docs-website/docs/img/ptt課程評價模板.png → docs-website/docs/早期文件/img/ptt課程評價模板.png b/docs-website/docs/img/ptt課程評價模板.png → docs-website/docs/早期文件/img/ptt課程評價模板.png
diff --git a/docs-website/docs/img/課程評價表單.png → docs-website/docs/早期文件/img/課程評價表單.png b/docs-website/docs/img/課程評價表單.png → docs-website/docs/早期文件/img/課程評價表單.png
diff --git a/docs-website/docs/img/鍵結關係.png → docs-website/docs/早期文件/img/鍵結關係.png b/docs-website/docs/img/鍵結關係.png → docs-website/docs/早期文件/img/鍵結關係.png
diff --git a/docs-website/docs/rust設置.md → docs-website/docs/早期文件/rust設置.md b/docs-website/docs/rust設置.md → docs-website/docs/早期文件/rust設置.md
diff --git a/docs-website/docs/前端設置.md → docs-website/docs/早期文件/前端設置.md b/docs-website/docs/前端設置.md → docs-website/docs/早期文件/前端設置.md
diff --git a/docs-website/docs/快速開始.md → docs-website/docs/早期文件/快速開始.md b/docs-website/docs/快速開始.md → docs-website/docs/早期文件/快速開始.md
diff --git a/docs-website/docs/資料庫設置.md → docs-website/docs/早期文件/資料庫設置.md b/docs-website/docs/資料庫設置.md → docs-website/docs/早期文件/資料庫設置.md
diff --git a/docs-website/docs/起源.md → docs-website/docs/早期文件/起源.md b/docs-website/docs/起源.md → docs-website/docs/早期文件/起源.md
diff --git a/docs-website/docs/概述/碳鍵是什麼.md b/docs-website/docs/概述/碳鍵是什麼.md
diff --git a/docs-website/docs/進階/HTTPS.md b/docs-website/docs/進階/HTTPS.md
@@ -0,0 +1,15 @@
+# HTTPS
+
+`frontend` 容器中的 Nginx 預設使用 HTTP ，然而 HTTP 傳輸明文，這導致許多安全隱患，例如，在公共網路中使用密碼登入時，若有惡意人士竊聽，將有洩漏密碼的危險。是故，正式上線的網站都應採用 HTTPS 來保證安全與隱私。
+
+本文提供兩種方式為碳鍵加上 HTTPS。
+
+## 方法一： 設定 Nginx 
+
+1. 申請 SSL 憑證，你可以在 [Let's Encrypt](https://letsencrypt.org/) 免費申請，或是其他供應商申請，但他們可能會收取費用。
+2. 按照 [Nginx 官方文件](http://nginx.org/en/docs/http/configuring_https_servers.html)修改 [Nginx 設定檔](https://github.com/carbon-bond/carbonbond/blob/master/frontend/app/web/deploy/nginx.conf)，為其加入 SSL 憑證的設定。
+3. 在本地端重新生成 `frontend` 的 docker 映像檔。(TODO:補充具體步驟)
+
+## 方法二： Caddy 反向代理
+
+Caddy 是一個 HTTPS 的伺服器軟體，無需任何設定，開箱即能使用 HTTPS。您可以在 443 埠口架設 Caddy ，再將所有請求反向代理給 `frontend`。這會是最容易的方法，但注意再增加一層反向代理是必帶來更多性能損耗。
diff --git a/docs-website/docs/進階/架構.md b/docs-website/docs/進階/架構.md
@@ -0,0 +1,10 @@
+# 架構
+
+碳鍵的 [docker-compose.yml](https://github.com/carbon-bond/carbonbond/blob/master/deploy/docker-compose.yml) 設定中包含四個 docker 容器，分別是 postgres, redis, frontend, api-service。
+
+其中的 frontend，是 Nginx 官方容器加上靜態檔案以及 [Nginx 設定檔](https://github.com/carbon-bond/carbonbond/blob/master/frontend/app/web/deploy/nginx.conf)，它監聽於 80 埠口，是瀏覽器直接接觸的容器，當收到請求時，frontend 會做兩件事情：
+
+- 若是靜態檔案請求，返回檔案內容
+- 若是 API 請求，將請求反向代理給 api-service
+
+![架構](./架構.svg)