chore: add docs, update 0.2.5

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ## 目录
 
+* [0.2.5](#025---2022-02-16)
 * [0.2.4](#024---2022-02-11)
 * [0.2.3](#023---2022-02-08)
 * [0.2.1](#021---2022-02-07)
@@ -16,7 +17,7 @@
 
 当前版本调整内容比较多，程序配置文件新增了一些配置项，请留意文档或阅读博客文章。
 
-如果你不希望手动调整程序配置文件，可以在备份当前数据目录 `app` 后，将其中的程序配置文件 `app/config.yml` 删除，重启应用，让程序自动更新和生成新版的配置文件。
+如果你不希望手动调整程序配置文件，可以在备份当前数据目录 `app` 后，将其中的程序配置文件 `app/config.yml` 删除，重启应用，让程序自动生成新版配置文件。
 
 - [新增] 用户登陆，让公网部署的小伙伴不必担心被陌生人随便修改配置的问题。
 - [新增] 免登陆模式，让 HomeLab、本地运行 Flare 的小伙伴，保持使用上的简单。

README.md

@@ -1,8 +1,8 @@
 # Flare ✨
 
-兼顾轻量快速、界面美观的个人导航页面，适用于 HomeLab 或其他注重私密的场景。
+轻量、快速、美观的个人导航页面，适用于 HomeLab 或其他注重私密的场景。
 
-无数据库依赖，使用简单的配置来保存数据，数据更加透明，并 100% 属于用户自己。
+无任何数据库依赖，应用数据完全开放透明，100% 属于用户自己。
 
 支持 x86 以及常见的 ARM 设备。
 
@@ -35,7 +35,7 @@ cd docker-flare
 启动应用非常简单，如果你习惯使用 Docker，可以执行：
 
 ```bash
-docker run --rm -it -p 5005:5005 -v `pwd`/app:/app soulteary/flare:0.2.4
+docker run --rm -it -p 5005:5005 -v `pwd`/app:/app soulteary/flare:0.2.5
 ```
 
 如果你习惯使用 docker-compose：
@@ -50,31 +50,33 @@ docker-compose up -d
 
 ![](./screenshots/lighthouse.png)
 
+## 进阶文档
+
+- [自定义启动参数](./docs/advanced-startup.md)
+- [关闭免登陆模式后，如何设置用户账号](./docs/application-account.md)
+- [如何挑选和使用图标](./docs/material-design-icons.md)
+
 ## 相比较 Flame
 
-- 服务资源消耗极低，可以跑在任何规格的机器上。
-- 程序页面性能非常好，渲染速度更快，支持渲染大量书签，而不必担心风扇起飞。
+- 服务资源消耗极低，可以跑在任何规格的机器上，甚至是一台搭载2015年S805芯片的ARM盒子。
+- 程序页面性能非常好，渲染速度更快，支持同时渲染大量（数千）书签，而不必担心风扇起飞。
 - 使用声明的配置来进行导航内容的管理，无需担心数据迁移问题。
 - 简化了天气数据的获取方式，不再需要申请天气网站的 `API_KEY` ，避免了不必要的成本开销。
-- 简化了 Flame 中的登陆、K8S、Docker 集成等不必要的功能。
-
-## 支持图标
-
-支持所有的 Material Design Icons，你可以在 [materialdesignicons.com](https://materialdesignicons.com/) 或 [pictogrammers.github.io/@mdi](https://pictogrammers.github.io/@mdi/font/6.5.95/) 6700 个精心设计的图标中找到你喜欢的图标。
-
-在配置中使用的图标名称无需使用连字符 `-`，直接输入名称即可。（大小写不敏感）
+- 简化了 Flame 中的K8S、Docker 集成等不必要的功能。
+- 内置了大量风格统一、高质量的矢量图标，减少选择困难症，确保界面长期“耐看”。
+- 默认使用免登陆模式，避免 HomeLab、本地使用的用户有额外的登陆操作。
 
-为了降低寻找和输入图标的成本，我将 `@mdi/font` 项目集成到了应用中，启动应用之后，访问 `/resources/mdi-cheat-sheets/` 可以打开图标列表页面。
+## 关于内置图标
 
-在页面中点击具体图标，可以使用的图标名称就自动复制到剪贴板中啦。
+程序内置了目前 [materialdesignicons.com](https://materialdesignicons.com/) 中所有的 Material Design Icons，你可以让你的每一个书签都拥有风格统一、高质量的矢量图标。
 
 ![](./screenshots/icon-cheat-sheets.png)
 
+更多信息，可以参考 [如何挑选和使用图标](./docs/material-design-icons.md)。
 
 ## TODO
 
-- [ ] 公网部署版本支持禁用设置
-- [ ] 完善程序设置功能
+- [ ] 持续完善程序定制化功能
 - [ ] 支持使用 API 进行内容管理
 - [ ] 支持自定义主题配色
 

docker-compose.yml

@@ -1,10 +1,20 @@
 version: '3.6'
 
 services:
-  flame:
-    image: soulteary/flare:0.2.4
+  flare:
+    image: soulteary/flare:0.2.5
     restart: always
+    # 默认无需添加任何参数，如有特殊需求
+    # 可阅读文档 https://github.com/soulteary/docker-flare/blob/main/docs/advanced-startup.md
     command: flare
+    # 启用账号登陆模式
+    # command: flare --nologin=0
+    # environment:
+      # 如需开启用户登陆模式，需要先设置 `nologin` 启动参数为 `0`
+      # 如开启 `nologin`，未设置 FLARE_USER，则默认用户为 `flare`
+      # - FLARE_USER=flare
+      # 指定你自己的账号密码，如未设置 `FLARE_USER`，则会默认生成密码并展示在应用启动日志中
+      # - FLARE_PASS=your_password
     ports:
       - 5005:5005
     volumes:

docs/advanced-startup.md

@@ -0,0 +1,44 @@
+# 自定义启动参数
+
+当前应用默认启动参数，包含以下四项目：
+
+```bash
+Usage of flare:
+  mr
+    	是否使用请求最小化模式
+  nologin
+    	启用无需登陆模式 (default true)
+  offline
+    	启用完全离线模式
+  port int
+    	指定监听端口 (default 5005)
+```
+
+## 合并资源请求：`mr`
+
+这个参数的作用是“合并页面请求资源，减少页面资源请求总数量”，在一些书签数据量极大的场景下，可以大幅提升页面渲染性能。
+
+小伙伴可以根据自己的情况按需开启，此参数默认关闭。
+
+启用方法，在 flare 启动参数后添加 `--mr=1`
+
+
+## 免登陆模式：`nologin`
+
+当这个参数关闭之后，用户需要在登陆之后，才能够对设置页面的内容进行调整，适合 Flare 在公网环境中使用的小伙伴。
+
+此参数默认开启，方便在 HomeLab 或本地使用的小伙伴，减少不必要的操作。
+
+禁用方法，在 flare 启动参数后添加 `--nologin=0`
+
+## 离线模式：`offline`
+
+当这个参数开启之后，flare 所有依赖公网的功能将被停用。
+
+目前 flare 仅会调用 issue[#4](https://github.com/soulteary/docker-flare/issues/4) 中提到的 `https://wis.qq.com/weather/common` 接口，获取天气数据，开启此参数后，天气将无法获取。
+
+此参数默认关闭，开启方法，在 flare 启动参数后添加：`--offline=1`
+
+## 指定端口：`port`
+
+这个参数用于自定义服务端口，使用 `docker-flare` 的小伙伴可以忽略。

docs/application-account.md

@@ -0,0 +1,47 @@
+# 用户账号相关
+
+flare 默认会启动免登陆模式，方便在 HomeLab 或本地使用的小伙伴。
+
+然而，有一些小伙伴需要在公网使用，本篇文档就来展示如何设置和获取 flare 的用户和密码。
+
+## 设置 Flare 账号和密码
+
+我们可以通过在环境变量中设置 `FLARE_USER` 和 `FLARE_PASS` 来指定 flare 的账号和密码，下面是一个容器编排文件示例：
+
+```yaml
+version: '3.6'
+
+services:
+  flare:
+    image: soulteary/flare:0.2.5
+    restart: always
+    # 默认无需添加任何参数，如有特殊需求
+    # 可阅读文档 https://github.com/soulteary/docker-flare/blob/main/docs/advanced-startup.md
+    # 启用账号登陆模式
+    command: flare --nologin=0
+    environment:
+      # 如需开启用户登陆模式，需要先设置 `nologin` 启动参数为 `0`
+      # 如开启 `nologin`，未设置 FLARE_USER，则默认用户为 `flare`
+      - FLARE_USER=flare
+      # 指定你自己的账号密码，如未设置 `FLARE_USER`，则会默认生成密码并展示在应用启动日志中
+      - FLARE_PASS=your_password
+    ports:
+      - 5005:5005
+    volumes:
+      - ./app:/app
+```
+
+当你使用 `docker-compose up -d` 启动应用之后，接着使用 `docker-compose ps`，就可以看到包含密码的日志输出啦：
+
+```bash
+docker-flare-flare-1  | 2022/02/16 14:11:14 用户未指定 `FLARE_USER`，使用默认用户名 flare
+docker-flare-flare-1  | 2022/02/16 14:11:14 用户未指定 `FLARE_PASS`，自动生成应用密码 7fc0e7cbc1356c93
+docker-flare-flare-1  | 2022/02/16 14:11:14 
+docker-flare-flare-1  | 2022/02/16 14:11:14 Flare v0.2.5-DD66850 linux/amd64 BuildDate=2022-02-16T13:36:31+0800
+docker-flare-flare-1  | 2022/02/16 14:11:14 
+docker-flare-flare-1  | 2022/02/16 14:11:14 服务端口 5005
+docker-flare-flare-1  | 2022/02/16 14:11:14 合并页面资源请求 false
+docker-flare-flare-1  | 2022/02/16 14:11:14 启用应用离线模式 false
+docker-flare-flare-1  | 2022/02/16 14:11:14 启用免登陆模式 true
+docker-flare-flare-1  | 2022/02/16 14:11:14 应用已启动 🚀
+```

docs/material-design-icons.md

@@ -0,0 +1,23 @@
+# Material Design Icons 使用
+
+为了方便小伙伴使用 flare，程序内置了来自 [materialdesignicons.com](https://materialdesignicons.com/) 中所有的 Material Design Icons，你可以让你的每一个书签都拥有风格统一、高质量的矢量图标。
+
+在示例的书签配置文件中，我们可以看到如何为应用配置图标。
+
+```yaml
+links:
+  - name: "Regexp 101"
+    link: "https://regex101.com/"
+    icon: "ladybug"
+    desc: "在线正则表达式"
+  - name: "JSON2Go"
+    link: "https://mholt.github.io/json-to-go/"
+    icon: "google"
+    desc: "快速生成结构体"
+```
+
+启动 flare 之后，使用浏览器访问 `/resources/mdi-cheat-sheets/` 可以打开图标列表页面。
+
+在页面中选择你喜欢的图标，鼠标点击之后，默认会将程序可以直接使用的“图标名称”保存在剪贴板，然后粘贴到配置文件中，flare 就会自动更新书签的图标啦。
+
+（图标名称无需使用 `-` 连字符，并且大小写不敏感）