docs

docs/advanced.md

@@ -0,0 +1,197 @@
+## 📄 `docs/advanced.md`
+
+```
+# Advanced Usage
+
+本页面包含 clash-for-linux 的 **高级用法与可选功能**。
+
+如果你已经能够正常完成以下事情：
+
+- 安装并启动 Clash 服务
+- 通过 SSH 转发访问 Dashboard
+- 使用 `proxy_on` / `proxy_off` 控制代理
+
+那么本页面的内容 **不是必须的**。  
+只有当你希望 **更精细地控制配置、网络行为或运行方式** 时，再继续阅读。
+
+---
+
+## 1. Mixin Configuration
+
+Mixin 用于在 **不直接修改主配置文件** 的情况下，
+对 Clash 配置进行 **追加或覆盖**。
+
+这是推荐的方式，用于长期维护和升级。
+
+### Default Behavior
+
+- 默认读取目录：`conf/mixin.d/`
+- 按文件名排序后依次合并
+- 后加载的文件会覆盖前面的配置
+
+### Example
+
+```yaml
+# conf/mixin.d/10-rules.yaml
+rules:
+  - DOMAIN-SUFFIX,example.com,DIRECT
+```
+
+修改完成后，重启服务即可生效：
+
+```
+clashctl restart
+```
+
+### When to Use Mixin
+
+- 添加自定义规则
+- 覆盖 DNS、rules、proxies 等配置
+- 避免每次更新订阅后手动修改 config.yaml
+
+------
+
+## 2. Tun Mode (Optional)
+
+Tun 模式用于实现 **系统级透明代理**，需要
+ **Clash Meta / Premium** 内核支持。
+
+⚠️ 启用 Tun 模式会影响系统网络行为，
+ 仅建议在你理解其作用与风险时使用。
+
+### Enable Tun Mode
+
+在 `.env` 中配置：
+
+```
+export CLASH_TUN_ENABLE=true
+export CLASH_TUN_STACK=system
+export CLASH_TUN_AUTO_ROUTE=true
+export CLASH_TUN_AUTO_REDIRECT=false
+export CLASH_TUN_STRICT_ROUTE=false
+export CLASH_TUN_DNS_HIJACK='any:53'
+```
+
+配置完成后重启服务：
+
+```
+clashctl restart
+```
+
+------
+
+## 3. systemd Behavior
+
+Clash 默认以 **systemd 服务** 的方式运行。
+
+### Service Characteristics
+
+- 服务异常退出时会自动重启
+- 配置文件错误会阻止服务进入运行态
+- 服务以低权限用户运行（默认 `clash`）
+
+### Check Service Status
+
+```
+systemctl status clash-for-linux.service
+```
+
+### View Logs
+
+```
+journalctl -u clash-for-linux.service -f
+```
+
+日志是排查问题时的 **第一入口**。
+
+------
+
+## 4. Multiple Subscriptions
+
+`clashctl` 支持管理多个订阅地址，
+ 并在不同订阅之间进行切换。
+
+### Basic Usage
+
+```
+clashctl sub add work https://example.com/work
+clashctl sub add personal https://example.com/personal
+```
+
+### Switch Subscription
+
+```
+clashctl sub use work
+```
+
+### Update Subscription
+
+```
+clashctl sub update
+```
+
+------
+
+## 5. Custom Binary
+
+在部分场景下，你可能希望使用：
+
+- 自行编译的 Clash 内核
+- 内网分发的二进制
+- 特定版本的内核
+
+你可以通过环境变量指定内核路径：
+
+```
+export CLASH_BIN=/path/to/clash
+```
+
+重启服务后生效。
+
+------
+
+## 6. Security Notes
+
+clash-for-linux 以 **安全默认配置** 为原则：
+
+- 管理接口默认仅监听 `127.0.0.1`
+- 推荐使用 SSH 端口转发访问 Dashboard
+- 不建议将 `external-controller` 暴露到公网
+
+如果你确实需要对外访问，请确保：
+
+- 已配置强随机 Secret
+- 已正确设置防火墙规则
+- 理解潜在的安全风险
+
+------
+
+## 7. Troubleshooting
+
+### Service Keeps Restarting
+
+- 检查 `conf/config.yaml` 是否存在语法错误
+- 查看 systemd 日志：
+
+```
+journalctl -u clash-for-linux.service -n 100
+```
+
+### Dashboard Not Accessible
+
+- 确认 `external-controller` 仅绑定在本机
+- 使用 SSH 端口转发方式访问
+- 确认服务处于 running 状态
+
+------
+
+## Final Notes
+
+本页面内容 **全部为可选功能**。
+
+如果你不确定是否需要其中某一项，
+ **最安全的选择是保持默认配置**。
+
+clash-for-linux 的设计目标是：
+
+> 一次安装，长期稳定运行，而不是频繁折腾。

docs/install.md

@@ -0,0 +1,255 @@
+## 📄 `docs/install.md`
+
+### 安装与可选参数
+
+```
+如果你只需要开箱即用的体验，直接运行：
+
+```bash
+sudo bash install.sh
+```
+
+即可完成安装。
+
+本页面仅在你需要 **自定义安装行为**（安装路径、运行用户、内核来源等）时才需要阅读。
+
+```
+---
+
+### 可选安装参数
+
+所有参数均通过 **环境变量** 在执行 `install.sh` 前指定。
+
+---
+
+### `CLASH_INSTALL_DIR`
+
+```bash
+CLASH_INSTALL_DIR=/opt/clash-for-linux
+```
+
+- Clash 的安装目录
+- 默认值：`/opt/clash-for-linux`
+- 适用场景：
+  - 多实例部署
+  - 特殊磁盘 / 数据目录
+  - 需要与系统目录结构对齐的服务器
+
+------
+
+### `CLASH_SERVICE_USER`
+
+```
+CLASH_SERVICE_USER=clash
+```
+
+- 指定运行 Clash 服务的系统用户
+- 默认值：`clash`（安装时自动创建）
+- 说明：
+  - 使用低权限用户运行是安全最佳实践
+  - 不建议使用 `root`
+
+------
+
+### `CLASH_ENABLE_SERVICE`
+
+```
+CLASH_ENABLE_SERVICE=true
+```
+
+- 是否创建 systemd 服务
+- 默认值：`true`
+- 设置为 `false` 时：
+  - 仅安装文件
+  - 不注册 systemd unit
+
+适用于：
+
+- 容器环境
+- 不使用 systemd 的系统
+- 二次开发或调试
+
+------
+
+### `CLASH_START_SERVICE`
+
+```
+CLASH_START_SERVICE=true
+```
+
+- 安装完成后是否立即启动服务
+- 默认值：`true`
+- 设置为 `false` 时：
+  - 安装完成后不自动启动
+  - 需手动执行 `clashctl start`
+
+------
+
+### `CLASH_AUTO_DOWNLOAD`
+
+```
+CLASH_AUTO_DOWNLOAD=auto
+```
+
+- 是否自动下载 Clash 内核
+- 可选值：
+  - `auto`（默认）：检测不到内核时自动下载
+  - `true`：强制重新下载
+  - `false`：关闭自动下载
+
+适用于：
+
+- 离线环境
+- 使用自定义内核
+- 内网服务器
+
+------
+
+### `CLASH_DOWNLOAD_URL_TEMPLATE`
+
+```
+CLASH_DOWNLOAD_URL_TEMPLATE=https://github.com/Dreamacro/clash/releases/latest/download/clash-{arch}.gz
+```
+
+- Clash 内核下载地址模板
+- `{arch}` 会自动替换为当前系统架构（如 `amd64`、`arm64`）
+
+适用于：
+
+- 使用私有镜像
+- 国内镜像加速
+- 自定义构建内核
+
+------
+
+### 使用示例
+
+```
+CLASH_INSTALL_DIR=/data/clash \
+CLASH_START_SERVICE=false \
+sudo bash install.sh
+```
+
+------
+
+> ⚠️ 提示
+>  如果你不清楚某个参数的含义，**不要设置它**。
+>  默认值已覆盖绝大多数使用场景。
+
+```
+---
+
+# 二、`advanced.md` 应该怎么写（这是“高手区”）
+
+## advanced.md 的一句话定位
+
+> **“当你已经能正常使用 Clash，但想用得更深、更稳、更可控时，再来看这里。”**
+
+所以它是：  
+👉 *可选*  
+👉 *不影响主流程*  
+👉 *不追求完整，只追求“有入口”*
+
+---
+
+## 📄 `docs/advanced.md`（推荐骨架）
+
+```md
+# 高级配置与进阶用法
+
+本页面包含 clash-for-linux 的高级用法与可选功能。
+如果你只关心基本代理与 Dashboard，可以跳过本页。
+```
+
+------
+
+## 1️⃣ Mixin 配置
+
+```
+## Mixin 配置
+
+Mixin 用于在不修改主配置的情况下，追加或覆盖 Clash 配置项。
+```
+
+### 默认行为
+
+- 默认读取目录：`conf/mixin.d/`
+- 按文件名排序后依次合并
+
+### 示例
+
+```
+# conf/mixin.d/rules.yaml
+rules:
+  - DOMAIN-SUFFIX,example.com,DIRECT
+```
+
+修改完成后重启服务：
+
+```
+clashctl restart
+```
+
+------
+
+## 2️⃣ Tun 模式（可选）
+
+```
+## Tun 模式
+
+Tun 模式用于实现系统级透明代理。
+该功能需要 Clash Meta / Premium 支持。
+```
+
+### 启用示例
+
+```
+export CLASH_TUN_ENABLE=true
+export CLASH_TUN_STACK=system
+export CLASH_TUN_AUTO_ROUTE=true
+```
+
+> ⚠️ Tun 模式会修改系统网络行为，仅建议在你理解其影响时启用。
+
+------
+
+## 3️⃣ systemd 行为说明
+
+```
+## systemd 行为说明
+
+Clash 默认以 systemd 服务运行。
+```
+
+- 服务失败会自动重启
+- 配置错误会阻止服务进入运行态
+- 日志查看：
+
+```
+journalctl -u clash-for-linux.service -f
+```
+
+------
+
+## 4️⃣ 多订阅管理（clashctl）
+
+```
+## 多订阅管理
+
+clashctl 支持多个订阅并进行切换。
+clashctl sub add work https://example.com/work
+clashctl sub use work
+clashctl sub update
+```
+
+------
+
+## 5️⃣ 安全说明（可选）
+
+```
+## 安全说明
+
+- 管理接口默认仅监听 127.0.0.1
+- 推荐使用 SSH 端口转发访问 Dashboard
+- 不建议将 external-controller 暴露至公网
+```