[DDraceNetwork](https://ddnet.org/) 是一款开源免费的多人合作平台跳跃游戏（其前身是 Teeworlds 的一个叫 DDRace 的模组），上限高游戏性强，是一个非常独特的合作游戏。本项目依赖众多好心的程序员进行维护，作为一个基本成熟稳定的 C++ 游戏项目，我们可以从这个项目中学习到很多开发相关的知识，甚至如果你有什么改进，也可以为原代码仓库提出 Issue 贡献 PR。



![image.png](https://vanblog.zerolacqua.top/static/img/681c4541ebc324951c184c717c6f7d0e.image.webp)



## 项目说明

### 项目环境配置

#### 基本配置

Fork 仓库后克隆代码

```bash
git clone --recursive git@github.com:YourUserName/ddnet.git
```

安装依赖

```bash
sudo apt install build-essential cargo cmake git glslang-tools google-mock libavcodec-extra libavdevice-dev libavfilter-dev libavformat-dev libavutil-dev libcurl4-openssl-dev libfreetype6-dev libglew-dev libnotify-dev libogg-dev libopus-dev libopusfile-dev libpng-dev libsdl2-dev libsqlite3-dev libssl-dev libvulkan-dev libwavpack-dev libx264-dev python3 rustc spirv-tools
```

构建项目

```bash
cmake -Bbuild
cmake --build build
```

如果构建的客户端无法连接服务端，有一种可能是你的 TUN 模式没关。


#### 代码格式化脚本

代码格式化检查，运行 `scripts/fix_style.py` 脚本。由于 Ubuntu 24.04 已经找不到 clang-format-10 的安装包，我们需要自行编译或通过其他途径安装：

- 使用 pip 安装（官方推荐）

    > A lot of the style offenses can be fixed automatically by running the fix script ./scripts/fix_style.py
    > 
    > We use clang-format 10. If your package manager no longer provides this version, you can download it from https://pypi.org/project/clang-format/10.0.1.1/.

    由于执行检查脚本使用的是 python，我们可以通过 pip 安装。如果是用 conda 安装的，在执行 python 脚本时指定 python 环境，就可以顺利运行检查。
    
    ```bash
    pip install clang-format==10.0.1.1
    ```

- 直接下载二进制文件

    https://aur.archlinux.org/packages/clang-format-static-bin
    
    下载后将二进制文件移动到 `/usr/local/bin` 目录下并重命令为 `clang-format-10`

    ```bash
    sudo mv /path/to/clang-format-10_linux-amd64 /usr/local/bin/
    cd /usr/local/bin/
    sudo chmod +x clang-format-10_linux-amd64
    sudo mv clang-format-10_linux-amd64 clang-format-10
    ```

- 通过源码编译（未尝试）

    ```bash
    git clone https://github.com/llvm/llvm-project.git
    cd llvm-project
    git checkout llvmorg-10.0.1

    mkdir build
    cd build
    cmake -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS=clang ../llvm
    make -j$(nproc)
    sudo make install
    ```
    
    编译过程中可能出现部分报错：
    - `std:numeric_limits` 不是 `std` 成员。在相关文件中包含 `#include <limits>` 即可
    - `uintptr_t` 未声明，在相关文件中包含 `#include <cstdint>` 即可


#### 运行单元测试

按项目自述文件操作

```bash
sudo apt install libgtest-dev
cd /usr/src/gtest
sudo cmake CMakeLists.txt
sudo make

# copy or symlink libgtest.a and libgtest_main.a to your /usr/lib folder
sudo cp lib/*.a /usr/lib
```

在我运行时，还需要安装 gmock

```bash
sudo apt install libgmock-dev
```

#### 使用 AddressSanitizer + UndefinedBehaviourSanitizer

> 这个博主配了但试不出来有什么东西，估计是没配置好吧

- 安装 Clang

    ```bash
    sudo apt install clang
    ```


- 编译命令

    ```
    CC=clang CXX=clang++ CXXFLAGS="-fsanitize=address,undefined -fsanitize-recover=address,undefined -fno-omit-frame-pointer" CFLAGS="-fsanitize=address,undefined -fsanitize-recover=address,undefined -fno-omit-frame-pointer" cmake -DCMAKE_BUILD_TYPE=Debug .
    make
    ```

- 运行命令

    ```bash
    UBSAN_OPTIONS=suppressions=./ubsan.supp:log_path=./SAN:print_stacktrace=1:halt_on_errors=0 ASAN_OPTIONS=log_path=./SAN:print_stacktrace=1:check_initialization_order=1:detect_leaks=1:halt_on_errors=0 LSAN_OPTIONS=suppressions=./lsan.supp ./DDNet
    ```

- 结果检查

    运行后，检查生成的 `SAN.*` 文件以查看详细的问题报告。ASan + UBSan 能够发现比 Memcheck 更多的问题，尤其是在内存错误和未定义行为方面。


:::info{title="相关信息"}
参见：https://github.com/ddnet/ddnet/tree/master
:::

#### 使用 VSCode 工作区

> 这个工作区配置挺折腾，中间没配好我真的非常沮丧……

在调试过程中，我发现一旦客户端代码命中断点，就会导致鼠标被游戏捕获无法释放的问题。在 dc 中询问后，Jupstar 大佬给我了一个解决方案。


:::warning{title="注意"}
修改桌面环境之后我的系统会经常报错，虽然不影响使用，但修改之前请考虑！
:::

- 按 `other/vscode/README.md` 的说明，下载相应的二进制文件和安装相应的包（其中 `clang-format` 可按前文所述安装）

    ```
    sudo apt install clangd clang-tidy lldb rustup mold ninja-build  xdotool
    ```
- 按照自述文件先按 `Ctrl+Shift+P` 输入 `Scan for kits` 扫描工具箱，再按 `Ctrl+Shift+P` 并选择 `Select a kit`,然后选 `[DDNet]` 开头的工具。

- 如果 cmake 生成时出现 rustup 相关报错，请执行命令：
    ```bash
    rustup default stable
    ```
- 查看一下当前显示是什么桌面环境，如果使用的不是 X11 的桌面环境，需要修改设置

    查看桌面环境：
    ```bash
    echo $XDG_SESSION_TYPE
    ```

    修改设置：
    ```bash
    sudo vim /etc/gdm3/custom.conf
    ```

    把该文件中这一行的注释状态解除：
    ```diff
    - # WaylandEnable=false
    + WaylandEnable=false
    ```
    然后重启即可切换。

注意：
- vscode 调试时需要从“运行与调试”（或者 F5）中进入
- **不要**点击 vscode 底部的 Cmake 调试按钮，否则走的不是工作区中定义的调试配置。这样虽然不会卡在 cmake 的 task 上，但因为没走工作区配置，鼠标指针释放的功能无法生效
- 工作区配置项似乎有点旧，当你使用“运行与调试”时，会卡在 cmake 的 task 上，原因不详。建议写一个 `.vscode` 的配置，然后不使用工作区打开。
    > 即不使用工作区配置，而是使用了自己 `.vscode` 文件夹中定义的配置。当然也可以直接修改工作区配置项 `other/vscode/ddnet.code-workspace` 不过这个文件是 git 跟踪过的，这个修改会被提交，所以建议在 `.vscode` 里自己创建一个，或者在分支里修改工作区配置，然后主分支不修改。

    - 使用自己写的 task，`type` 改为 `shell` 的：
        ```json
         {
                "version": "2.0.0",
                "tasks": [
                        {
                                "type": "shell",
                                "label": "CMake: build client (shell)",
                                "command": "cmake",
                                "args": [
                                        "--build",
                                        "${workspaceFolder}/build",
                                        "--target",
                                        "DDNet"
                                ],
                                "group": {
                                        "kind": "build",
                                        "isDefault": true
                                },
                                "problemMatcher": [],
                                "detail": "Build client targets (shell)"
                        },
                        {
                                "type": "shell",
                                "label": "CMake: build server (shell)",
                                "command": "cmake",
                                "args": [
                                        "--build",
                                        "${workspaceFolder}/build",
                                        "--target",
                                        "DDNet-Server"
                                ],
                                "group": {
                                        "kind": "build",
                                        "isDefault": true
                                },
                                "problemMatcher": [],
                                "detail": "Build server targets (shell)"
                        }
                ]
        }
        ```
    - 然后运行与调试选择你自己配置的 `launch` 配置：
        ```json
        {
                "version": "0.2.0",
                "configurations": [
                        {
                                "type": "lldb",
                                "request": "launch",
                                "name": "Launch client",
                                "program": "${workspaceFolder}/build/DDNet",
                                "preLaunchTask": "CMake: build client (shell)",
                                // use dbg configs like this
                                // "args": [ "dbg_gfx 0" ],
                                // enable this to start the debugger with TSAN
                                // "environment": [ { "name":"TSAN_OPTIONS","value":"ignore_noninstrumented_modules=1" }],
                                "cwd": "${workspaceFolder}/build",
                        },
                        {
                                "type": "lldb",
                                "request": "launch",
                                "name": "Launch server",
                                "program": "${workspaceFolder}/build/DDNet-Server",
                                "preLaunchTask": "CMake: build server (shell)",
                                "cwd": "${workspaceFolder}/build"
                        },
                        // useful for cross debugging the windows (wine) client
                        // for these you need the microsoft cpp extension
                        // start the wine executable like this:
                        // winedbg --gdb --no-start --port 55555 DDNet.exe
                        {
                                "type": "cppdbg",
                                "request": "launch",
                                "name": "Attach to wine gdbserver",
                                "program": "${workspaceFolder}/build_win/DDNet.exe",
                                "miDebuggerServerAddress": "localhost:55555",
                                "cwd": "${workspaceFolder}/build_win/",
                                "MIMode": "gdb",
                                "setupCommands": [
                                        {
                                                "description": "Auto styling for \"gdb\"",
                                                "text": "-enable-pretty-printing",
                                                "ignoreFailures": true
                                        }
                                ]
                        }
                ]
        }
        ```


:::info{title="相关信息"}
参见：https://github.com/ddnet/ddnet/blob/master/other/vscode/README.md
:::



### 项目结构

- `src/base` 目录

    由于DDNet是一个跨平台游戏，需要一个抽象层来简化开发，因此该目录包含许多有用的函数来处理这一问题。



- `src/engine` 目录

    游戏引擎所在位置，它处理大多数与玩法无关的东西，比如图形、声音、网络等。



- `src/game` 目录

    所有玩法的代码所在位置，分为客户端和服务器。



    - 服务器端
    
        - 这个游戏使用自己的面向对象的实体分级系统，所有其他实体源于主类 `CEntity`，位于 `src/game/server/entity.h` 目录。

        - 游戏世界在 `src/game/server/gameworld.h` 路径下，管理这些实体。

        - 一些重要实体有：

            - `CCharacter`：代表一个活着的 Tee, 当一个 Tee 生成时会被实例化，当它死亡时会被删除。
            - `CPlayer`：包含了其他没有关联 Tee 的信息（昵称、国籍等）。有关玩家在死亡之间的信息，请参阅此项。


    - 客户端
    
        客户端由许多组件构成，都是在 `src/game/client/component.h` 中定义的继承 `CComponent` 的类：这些组件通过实现视觉方法来提供功能，例如 `OnInit`，`OnMessage` 等等。



    - 网络
    
        网络协议几乎由 python 脚本生成并输出 c++ 代码，例如说，`datasrc/network.py` 定义了所有网络包。

:::info{title="相关信息"}
参见：https://wiki.ddnet.org/wiki/Development/zh

文档：https://codedoc.ddnet.org/
:::

### 贡献代码指南

- 贡献前的准备

    在编写代码前，建议先开一个 issue 讨论想法，确保贡献符合 DDNet 项目的理念。常见的被拒绝贡献包括：
    - 影响游戏玩法的 dummy 扩展
    - 破坏向后兼容性的改动（如网络协议、文件格式或游戏玩法）。

- 编程语言

    DDNet 主要使用 C++，少量使用 Rust，Python 用于代码生成和工具，CMake 用于构建。平台特定代码可能使用 Java（Android）或 Objective-C++（macOS），但不接受其他语言的代码。

- 代码风格

    命名规则：变量、方法和类名使用大驼峰命名法（如 `MaxLength`），避免单字母变量名。

    匈牙利命名法：继承自 Teeworlds，使用前缀如 `m_`（类成员）、`g_`（全局变量）、`p`（指针）等。

    现代 C++ 实践：优先使用 `nullptr`、`true`/`false`，避免 `goto`、默认参数和方法重载。

    代码格式化：使用 clang-format 10 自动格式化代码。

- 最佳实践

    避免在 `if` 语句中赋值：明确分离变量赋值和条件判断。

    Getter 方法命名：避免使用 Get 前缀（如 `MyVariable()` 优于 `GetMyVariable()`）。

    类成员初始化：在声明时直接初始化类成员变量。

    文件命名：使用小写字母和下划线分隔（如 `foo_bar.cpp`）。

- 提交消息
    
    提交消息应描述对玩家/用户的影响，而非技术细节，以便直接用于变更日志。

:::info{title="相关信息"}
参见：https://github.com/ddnet/ddnet/blob/master/CONTRIBUTING.md
:::

## 开始贡献

### Good first issue

*goog first issue* 的作用是什么？

- 一般是开源仓库中比较简单的 issue，可能几行代码就能解决，甚至让人有一种捡漏的感觉，一般会由项目维护者选择简单易上手的、无关痛痒的问题，不亲自处理而是留待潜在的贡献者处理，可以吸纳新人参与到项目贡献中。
- 对于没有什么提交经验的人，面对一个复杂的项目，这种简单的 issue 可以帮助参与者建立对流程的基本认识。对贡献者来说，自己提交的 pr 能被合并是非常有成就感的，尤其是首先提交 pr 的贡献者，看到自己的修改被合并还是很高兴的。

比如我找的这个 issue：https://github.com/ddnet/ddnet/issues/9583 是个很简单的工作，只需要把描述文本修改一下就行。


另外，[这个网站](https://goodfirstissue.dev/)可以帮助你查看流行开源项目中可能的 *goog first issue*。

### PR 常用技巧

- 在 PR 中提及要解决的 issue，一般可以用 `fix#xxxx` 或 `close#xxxx`，这样 github 会自动渲染出链接的 issue 并会提示 PR 将关闭这个 issue
- 想要验证其他人还未被合并的 PR？

    在你已经 Fork 了自己的仓库，并且克隆到本地的基础上，先要添加 ddnet 官方的上游仓库：
    
    ```bash
    git remote add upstream git@github.com:ddnet/ddnet.git
    ```
    
    然后，根据你要拉取的 PR 编号进行拉取，比如我想拉取 ＃9786 PR，我就从 `upstream` 拉取 `pull/9786/head`，然后把这个本地分支命名为 `keb-pr`:
    
    ```bash
    git fetch upstream pull/9786/head:keb-pr
    ```
- 在 issue 中插入视频，直接拖入即可 ｀.mp4｀ 最佳，可直接渲染出播放窗口
- 在 issue 中引用特定提交的代码。在 github 某个提交的代码浏览的界面里，点选行号（按住 shift 可以选择范围），点击菜单选择 `Copy permalink` 即可，以下链接会被 github 渲染成相应区域的代码块：

    > https://github.com/ddnet/ddnet/blob/0aff2c75322a99a218fc6a8d659e8e77d62928e4/src/test/editor.cpp#L5-L8

## 其他的话

### 调整心态

参与代码贡献是一件令人振奋的事情，但中间也会遇到一些会让你感到受挫的事情，你需要以平常心看待它们。

- 项目维护者对你的 PR 的 review 可能比较严格

    一般是因为你的提交存在一些问题，或者不规范的地方，如要求你压缩你的提交，修改提交信息等。正视它们，这些直率的建议也能让你进步的更快。
    
- 社区的评价不一定都是中听的

    社区对你的贡献的评价也可能让你不舒服，尽管他们看起来并没有恶意。比如我贡献一个提交，想获取 dev 身份组时，会有人用 “commit: readme typo fix” 来打趣我（而且这种开源贡献笑话还挺常见的，时不时就会出现一次）。
    
    面对这种情况，还是要调整好心态，如果想要做长期的贡献还是从简单的 issue 开始的。跟进时间长了自然会做出有价值的提交。而且即使是简单的拼写修复提交，仓库的维护人员也一直欢迎和接纳，不要太受社区人员的影响。同时也需要自己提升心理承受能力。

- 开源社区终究也是社区，你并不突出

    社区总有光彩夺目的人，你需要降低期待做好无人理睬的准备。在 Manim 幼儿园的时候就已经有这种无力感了，更别说外国社区，英语蹩脚没有熟人更会让你觉得自己是被无视了。DDNet 社区里虽然有几位国人版主和贡献者，但也都根本没有接触过，颇有一种孤军奋战的感觉。
    
### 大胆去问
 
在 github 上找了个几个月前的 issue，里面提到了了一个小 BUG，我的开发就从地图编辑器开始了。

随着慢慢深入源码，我可以发现代码中其实有很多可以改进的地方，不知不觉已经提了五个 PR 了。在这个过程中，可能会有自己的 PR 或者 issue 没有被仓库协作者看到的情况。你可以大胆地在 DC 群里去请求 review。当然遇到了编程相关的问题，也可以去问问 DC 里的人，如果有了解相关的代码的人，是会给予你帮助的。即使他们可能没有负责这部分的代码，他们也可以为你提供一些有价值的建议。

另外，这次有了五个 PR 之后，我也是鼓起勇气去 @ 了管理员，最后也是如愿以偿地得到了开发者的 role，所以还是得要大胆一点，只要你不犯大病礼貌一点，不会有什么惩罚的。

DDNet 项目贡献杂记

其实这已经不是我第一次折腾双系统了。我的笔记本是惠普战 66 六代酷睿版，笔记本上之前装了双系统，但是分的空间太少了，所以这次打算加装一个硬盘，将**双系统装在双硬盘上**。



## 准备工作

### 制作启动盘


启动盘制作工具使用 [Rufus](https://rufus.ie/zh/)
。


| 设置项 |  信息 |
| --- | --- |
| 镜像 | Ubuntu 24.04 |
| 分区类型 | MBR |
| 目标系统类型 | BIOS 或 UEFI|
| 文件系统 | FAT32（默认） |
| 簇大小 | 16K 字节（默认） |

### 添加硬盘

购置了梵想的 1T NVMe SSD M.2 2242 硬盘，用于安装 Ubuntu。

装机时需要注意参照官方装机说明进行，断开电池拼接，去除身上的静电（或使用防静电手套），再安装硬盘。

## 双系统安装

原先的双系统是都安装在 `nvme0` 上的 Ubuntu 版本是 22.04 有部分配置信息，还有密钥什么的是需要迁移的，其他的重装之后再安装吧。

### 安装 Ubuntu 24.04

插入启动盘，在开机时连按 `Esc` 进入 BIOS 设置（不同机型操作可能不同）。把 USB 设置为优先启动项进行安装。

安装中，因为我是新加的一个空盘，所以我选择了清空硬盘安装的选项。安装前一定要注意别清错盘了，清空硬盘的选项只有 `nvme0` 和 `nvme1` 两个，但不清楚硬盘和名称的对应关系。可以先进入手动安装模式，查看自己的 Windows 系统和数据在哪个盘上。

### 卸载 Ubuntu 22.04

旧的 Ubuntu 系统与 Windows 位于同一个硬盘上，通过 Windows 的磁盘管理工具，删除 Ubuntu 所在的分区。然后利用 DiskGenius （或者其他方法如 `diskpart` 命令为 System 分区分配盘符）删除 EFI 目录中的 ubuntu 文件。

当然卸载完 Ubuntu 之后，可能会在 GRUB 中残留它的引导项。

可执行以下命令，生成新的 `grub.cfg` 文件，以更新 GRUB 配置


``` bash
sudo grub-mkconfig -o /boot/grub/grub.cfg
````

这个命令会根据配置文件自动生成 `grub.cfg`，确保所有更改都被应用。

更新后，记得将 `grub.cfg` 文件的权限恢复为只读状态。
``` bash
sudo chmod 444 /boot/grub/grub.cfg
```
重新启动之后，GRUB 将正常显示引导项，原有的无效引导将被清除。


参考：https://developer.aliyun.com/article/1534371



## 新系统的配置


### 配置密钥

其实如果密钥用的地方不多的话，最好还是在新系统上重新生成一个。直接复制到新系统的 `.ssh` 里并不管用，首先需要确保拷贝的密钥具有正确的权限

```bash
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_rsa
chmod 644 ~/.ssh/id_rsa.pub
```


还可能需要用 `ssh-add` 添加到 `ssh-agent` 中


### 配置输入法

我使用的输入法是五笔的，运行以下命令（其中 `ibus-qt4` 可能已经无法定位到包了）：

```bash
sudo apt-get install ibus ibus-clutter ibus-gtk ibus-gtk3 ibus-qt4
im-config -s ibus
sudo apt-get install ibus-table-wubi
ibus-setup
ibus-daemon -drx
```

然后在键盘设置中，选择中文（极点五笔）即可。

### 安装常用软件

- 代理相关软件

    - 由于 CFW 停止更新和维护，在新版本的 Ubuntu 上可能无法运行，目前还没有找到问题。因此换用了 clash-verge-rev 版本，基本操作都十分类似。
    
- 编程相关软件
    
    - 安装 vscode，用账号同步一些配置和插件

- 生产力相关软件

    - 安装 Chrome，用账号同步插件。
    - 安装大纲笔记软件 Workflowy。由于其安装包是 Appimage 格式的，初次使用可能无法使用（权限问题，或者缺少 `libfuse`）。可以参考文章：https://linux.cn/article-14619-1.html
    
### 配置常用开发环境

- 安装常用的工具（更新中）

    ```bash
    sudo apt-get install git vim build-essential
    ```

- 安装 nvm

- 安装 Docker

    ```bash
    curl  -fsSL  https://download.docker.com/linux/ubuntu/gpg| sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/docker.gpg
    echo "deb https://download.docker.com/linux/ubuntu  noble stable" | sudo tee /etc/apt/sources.list.d/docker.list
    sudo apt install docker-ce docker-ce-cli  docker-buildx-plugin docker-compose-plugin containerd.io
    ```

双系统安装实录

一般机场下载下来的配置都自带很多的规则，但是有时自己需要针对特定的域名和 IP 进行优化。**Clash for Windows** 的 Mixin 功能，以及 **Clash Verge** 的全局扩展配置和全局扩展脚本，让我们能在不修改原始配置文件情况下，自由定制配置的能力。



## 前言

我的 Clash 在规则模式下：

- cdn 走了国外的流量
- 一个游戏国内路线更流畅
- 访问一些外国网站，走代理反而会访问失败

如此种种，虽然下载的配置文件中为我设定了详细的规则。但我总希望我能自己定义一些规则，由于就有了这篇文章。

## 简单粗暴——修改配置文件

可以直接修改对应机场的配置文件中的 `rules`

```
rules:
 - DOMAIN-SUFFIX,cn.bing.com,DIRECT
 - DOMAIN-SUFFIX,zhuanlan.zhihu.com,DIRECT
 - DOMAIN-SUFFIX,zerolacqua.top,DIRECT
 - DOMAIN-SUFFIX,docs.opencv.org,DIRECT
```

对我来说 `DOMAIN-SUFFIX` 就够用了，这样就能完成自定义规则。

但是这么做有一个问题，修改的规则是在配置文件中的，哪天你更新了配置文件（代理的配置文件一般都会经常更新），你的自定义规则就没有了。那如何避免直接在代理的配置文件中进行修改呢？

## 规则覆盖

**Clash for Windows** 的 **Mixin** (yml) 模式，以及 **Clash Verge** 的**全局扩展配置**（yml），能在不配置原配置文件的基础上，通过编写额外的规则<b>覆盖</b>原有的规则。不管你切换到了哪个代理的配置，这个规则都能适用。

下面以 mixin 为例：

```yaml
mixin:
  rules:
    - "DOMAIN-SUFFIX,zerolacqua.top,DIRECT"
    - "DOMAIN-SUFFIX,zhuanlan.zhihu.com,DIRECT"
```

这样，当访问 `*.zerolacqua.top` 或者 `*.zhuanlan.zhihu.com` 时，就会直接走 `DIRECT` 流量。

但是这样做还是有问题，那就是 yml 中定义的 `rules` 字段将把原配置文件中 `rules` 覆盖掉。导致代理配置中定义的那么多规则全部没了。当然，你可以选择把代理配置中的规则复制进 yml 中，不过这肯定不是期望的方法。

## Diff 模式/编辑规则

- **Clash for Windows**

    **Diff** 模式可以让我们既做到增量式地添加规则，不过针对每个配置文件，Diff 都是独立的，如果有多个配置文件，那么你就要定义多次 Diff。

    ```diff
    rules:
    + - DOMAIN-SUFFIX,cn.bing.com,DIRECT
    + - DOMAIN-SUFFIX,zhuanlan.zhihu.com,DIRECT
     - DOMAIN-SUFFIX,bilibili.com,🌏 爱奇艺&哔哩哔哩
    ```

    比如你在 Diff 中添加了如上的两行，那么每次更新配置后，你所做的修改都会应用在这个配置文件上。


- **Clash Verge**
    
    **编辑规则**、**编辑代理组**提供了可视化 UI，可以添加、删除规则（或代理组），编辑结果不会修改配置文件，效果与 **Clash for Windows** 的 Diff 类似。



## 脚本模式

Diff 模式/编辑规则似乎已经帮助我们解决了问题，但有一点遗憾的地方是，每个代理配置文件都需要单独进行配置。有没有更好的办法，让我“一处配置、处处生效”？

- **Clash for Windows**

    Mixin 除了 yml 格式，还有 js 格式的（需要在设置中打开）。在 js 格式中，Clash 给出了默认的配置：

    ```js
    module.exports.parse = ({ content, name, url }, { yaml, axios, notify }) => {
      return content
    }
    ```

    修改：

    ```js
    module.exports.parse = ({ content, name, url }, { yaml, axios, notify }) => {
      const extra = { 
        rules: [
          'DOMAIN-SUFFIX,cn.bing.com,DIRECT',
          'DOMAIN-SUFFIX,zhuanlan.zhihu.com,DIRECT',
          ...content.rules,
        ],
      }


      return { ...content, ...extra }
    }
    ```

    这里 `content` 是配置文件的结构化数据，将 `rule` 属性进行修改，添加上需要的内容即可。

    参见：https://blog.in-x.cc/tech/other/cfw-mixin

- **Clash Verge**

    按官网提供的方法设置规则：

    ```js
    /**
     * 配置中的规则"config.rules"是一个数组，通过新旧数组合并来添加
     * @param prependRule 添加的数组
     */
    const prependRule = [
      // 将百度分流到直连
      'DOMAIN-SUFFIX,cn.bing.com,DIRECT',
      'DOMAIN-SUFFIX,zhuanlan.zhihu.com,DIRECT',
    ];
    function main(config) {
      // 把旧规则合并到新规则后面(也可以用其它合并数组的办法)
      let oldrules = config["rules"];
      config["rules"] = prependRule.concat(oldrules);
      return config;
    }
    ```

    参见：https://www.clashverge.dev/guide/rules.html?h=%E5%85%A8#_4

Clash 灵活配置规则

Tabby （前身是 Terminus）是一款高度可配置的终端模拟器、SSH 和串口客户端，支持 Windows，macOS 和 Linux。



:::info{title="相关信息"}
官网地址：https://tabby.sh/
:::




## 基本信息

Tabby 是什么：
- Tabby 是 Windows 标准终端 (conhost)、PowerShell ISE、PuTTY、macOS Terminal.app 和 iTerm 的替代品
- Tabby 不是一个全新的 shell，也不是 MinGW 或 Cygwin 的替代品。
- 它也不是轻量级的 - 如果你对内存的占用很敏感，请考虑 Conemu 或 Alacritty


它的主要功能有：

- 集成 SSH，Telnet 客户端和连接管理器
- 集成串行终端
- 定制主题和配色方案
- 完全可配置的快捷键和多键快捷键
- 分体式窗格
- 自动保存标签页
- 支持 PowerShell（和 PS Core）、WSL、Git-Bash、Cygwin、MSYS2、Cmder 和 CMD
- 在 SSH 会话中通过 Zmodem 进行直接文件传输
- 完整的 Unicode 支持，包括双角字符
- 不会因快速的输出而卡住
- Windows 上舒适的 shell 体验，包括 tab 自动补全（通过 Clink）
- 为 SSH secrets 和设置集成了加密容器
- SSH、SFTP 和 Telnet 客户端可用作 Web 应用（也可托管）



## SFTP

Tabby 集成了 SFTP，可以通过面包屑切换路径，并支持上传和下载文件，还允许拖拽上传文件。但比较遗憾的是，截止目前（2024.12.8），还没办法上传/下载文件夹。

要在终端中确定远程 Shell 的路径，以实现复制文件路径和在当前路径下打开 SFTP 等功能，需由 iTerm 实现的 OSC 1337 协议报告其 CWD。参考：https://github.com/Eugeny/tabby/wiki/Shell-working-directory-reporting

我的远程服务器使用 bash，因此我需要在 `~/.bash_profile:` 文件中添加以下语句：
```bash
export PS1="$PS1\[\e]1337;CurrentDir="'$(pwd)\a\]'
```

## 配置和连接

### 命令行

可以保存自己常用的命令行，即按指定的参数执行特定命令。

比如在使用 natapp（frp 也是同理）时，需要通过命令行启动，因此我们可以新建配置，使用 CMD 模板，在命令行一栏设置：
``` cmd
cmd.exe /k natapp.exe
```

``` cmd
cmd.exe /k frpc.exe -c frpc.toml
```
并指定命令的工作路径，就可以直接通过这个配置启动内网穿透。

或者为 MongoDB 设置启动命令：

``` cmd
mongod.exe --dbpath\=g:\\xxx
```
Tabby 贴心地准备了不带转义字符的参数输入项，再也不怕参数不对了。

当然配置项里还可以设置环境变量和是否以管理员身份运行。比如 MongoDB 就需要管理员身份运行。

### SSH 配置

Tabby 可以从 `.ssh/config` 中自动导入连接配置，如果你使用过如 vscode 等 IDE 远程连接功能，你就应该知道这个配置项有多方便。

但是值得一提的是  `Host` 字段中最好不要带 `@` 否则会被直接当 ssh 命令解析了。

从 `.ssh/config` 中导入的连接配置，如果存在 `"` （比如 vscode 生成的配置）会造成密钥路径解析失败，导致远程连接无法建立，目前这个问题依然存在，如果遇到请手动修改去掉 `"`。参见：https://github.com/Eugeny/tabby/issues/7875

Tabby 配置使用记录

如果有部署在内网上的 web 服务，想要通过公网进行访问（比如本地部署的测试），可以借助公有或自建的内网穿透完成。本文使用 frp 进行内网穿透服务的搭建。

:::info{title="相关信息"}
仓库地址：https://github.com/fatedier/frp

文档说明：https://gofrp.org/zh-cn/docs/
:::




## frp 简介

根据 GitHub 上的描述，frp 是一个专注于内网穿透的高性能的反向代理应用，支持 TCP、UDP、HTTP、HTTPS 等多种协议，且支持 P2P 通信。可以将内网服务以安全、便捷的方式通过具有公网 IP 节点的中转暴露到公网。


## frp 安装和启动

在 Release 页面下载客户端和服务端，由于云服务器和个人设备的系统不一致，需要分别下载两个系统上的安装包（安装包内有客户端和服务端的程序）。

服务端保留 `frps` 和 `frps.toml` 配置文件（linux），而客户端保留 `frpc.exe` 和 `frpc.toml` 文件（windows）。

安装完成之后就可以在命令行中启动了。有一点需要注意，由于程序的需要在命令行中启动，我希望在我的 **Tabby** 终端中添加一个 frp 启动配置，因此配置项应该写成如下形式。

```
cmd.exe /k frpc.exe -c frpc.toml
```

由 `cmd.exe` 接收要执行的程序，以及该程序的参数（这里是 `-c frpc.toml`）。使用 `/k` 或 `/c` 参数设置要执行的程序，前者在执行的程序退出后命令行继续保留，而后者命令行会退出。

在 Ubuntu 中就直接设置以下命令即可：

```
./frpc -c frpc.toml
```


## frp 的配置

根据用途的不同，官网给出了不同的配置示例。我们的需求是访问内网的 Web 服务。

注意：
- 服务端和客户端都需要 `-c` 参数
- 不同版本的安装包内默认的配置文件格式不同，所以各个教程中的配置语法也不尽相同
- 不同版本的配置变量名也有一定的区别，请参考对应的文档

### 基础配置

- 服务端配置文件
    
    ```toml
    bindPort = 7000
    vhostHTTPPort = 8090
    ```
    
    服务端设置内网穿透服务端监听端口 `bindPort` 和 	HTTP 类型代理监听的端口 `vhostHTTPPort`。
    

- 客户端配置文件

    ```toml
    serverAddr = "xxx.xxx.xxx.xxx"
    serverPort = 7000

    [[proxies]]
    name = "web"
    type = "http"
    localPort = 8090
    customDomains = ["frp-test.zerolacqua.top"]
    ```
    
    客户端设置连接服务端的地址 `serverAddr` 和端口 `serverPort`（与服务端 `bindPort` 一致）。
    每个 `[[proxies]]` 表示一个代理项，要设置代理的类型、本地端口，`customDomains` 用于设置 `http` 类型，可通过 `customDomains` 访问本地的 `localPort`。

### 管理页面

frp 可以在指定端口开启管理界面，包括服务端的面板和客户端的管理界面。`auth.token` 用于验证客户端。`webServer` 则是相应的面板设置。


- 服务端配置文件

```toml
auth.token = "token"

webServer.addr = "0.0.0.0"
webServer.port = 7500
webServer.user = "user_name"
webServer.password = "password"
```

- 客户端配置文件

```toml
auth.token = "token"

webServer.addr = "127.0.0.1"
webServer.port = 7400
webServer.user = "user_name"
webServer.password = "password"

[[proxies]]
name = "admin_ui"
type = "tcp"
localPort = 7400
remotePort = 7400
```

如果需要访问客户端（本地）的管理界面，只需将其也进行内网穿透。注意这里使用 `tcp` 类型。`tcp` 类型可以配置多端口。

## 其他问题

如果想让服务端在会话结束后继续运行，可以使用 tmux 进行管理。