my-singbox 0.0.0-stage → 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zht7063
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+**English** | [简体中文](README_CN.md)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# My sing-box
+
+Shadowsocks 2022 and VLESS-Reality-Vision nodes with sing-box in Docker; exports `clash.yaml` for Mihomo clients.
+
+Supported: Debian and Ubuntu VPS only, x64 or arm64.
+
+```bash
+curl -fsSLo install.sh https://raw.githubusercontent.com/zht7063/my-singbox/ts-version/install.sh
+sh install.sh && export PATH="$HOME/.local/node/bin:$PATH"
+```
+
+The installer installs Node >= 22 to `~/.local/node` without sudo; it skips installation if Node >= 22 is already on PATH.
+
+Install the CLI from npm:
+
+```bash
+npm i -g my-singbox   # then run "my-singbox <cmd>"
+```
+
+Or run it without installing: `npx my-singbox <cmd>`. Examples below use `npx my-singbox <cmd>`; after a global install, drop `npx`. Run commands from the deployment directory (for example `/opt/sing-box`).
+
+## Usage
+
+Requirements: Node >= 22, Docker with the Compose plugin, access to the Docker socket, and optionally `ss` for the UDP check.
+
+### init
+
+In a writable deployment directory, such as `/opt/sing-box`, run:
+
+```bash
+npx my-singbox init
+```
+
+`init` runs doctor, copies `compose.yaml` if missing, generates missing credentials and configs, starts sing-box, checks it, and prints firewall and client import instructions. It keeps existing files on re-run and never uses sudo.
+
+### start
+
+```bash
+npx my-singbox start
+```
+
+`start` runs Docker Compose and checks that the container stays running, its config passes `sing-box check`, and configured TCP ports accept local connections. It also checks UDP 8388 with `ss` when available and prints container logs on self-check failure.
+
+### isp-outbound
+
+```bash
+npx my-singbox isp-outbound --add
+npx my-singbox isp-outbound --remove
+```
+
+Add an ISP SOCKS5 outbound (it asks for the proxy address and credentials) or remove it. Without an action, the command shows a menu; `--yes` or `-y` skips restart confirmation, and `--help` shows options. Add creates `shadowsocks-isp` on 13839 TCP/UDP and `vless-reality-isp` on 18444 TCP, adding them to `clash.yaml` when it exists. Re-import it in the client. The command saves backups in `.isp-backup`; removal restores a pre-ISP backup, so later edits to managed files are not retained in the restored files. It does not change firewall rules.
+
+### doctor
+
+```bash
+npx my-singbox doctor
+```
+
+Read-only checks for Node version, Linux and libc, architecture, Docker Compose, and Docker socket access. `OK`, `WARN`, and `FAIL` describe each result; failures produce a nonzero exit status.
+
+| Command | Purpose |
+| --- | --- |
+| `init` | Prepare missing files and start sing-box. |
+| `gen-keys` | Generate `.env` credentials; needs `SING_BOX_VERSION` (image tag) set in the environment when run on its own. |
+| `gen-config` | Generate the server config. |
+| `conf-clash` | Generate the client config. |
+| `start` | Start sing-box and run self-checks. |
+| `isp-outbound` | Add or remove the ISP outbound. |
+| `doctor` | Check prerequisites. |
+
+Use `npx my-singbox --help` or `-h` for command help. For manual setup, copy `compose.yaml` into the deployment directory and run:
+
+```bash
+SING_BOX_VERSION=v1.14.4 npx my-singbox gen-keys
+npx my-singbox gen-config
+npx my-singbox conf-clash
+npx my-singbox start
+```
+
+## Firewall and ports
+
+Open 8388/tcp, 8388/udp, and 8443/tcp in the local firewall and cloud security group. For ISP outbound, also open 13839/tcp, 13839/udp, and 18444/tcp. The tool never changes firewall rules.
+
+## Install Docker
+
+```bash
+curl -fsSL https://get.docker.com | sudo sh
+sudo usermod -aG docker "$USER"
+```
+
+Log out and back in, or run `newgrp docker`. Docker group membership is equivalent to root access.
+
+## Unsupported systems
+
+Only Debian and Ubuntu are supported; all other distributions are unsupported. `install.sh` and doctor also exit with an error on Alpine/musl, on glibc older than 2.28, and on CPU architectures other than x64 and arm64. Use the [shell version v1.1.0](https://github.com/zht7063/my-singbox/releases/tag/v1.1.0) (branch [`shell-version`](https://github.com/zht7063/my-singbox/tree/shell-version)) instead.
+
+## Files and config
+
+The deployment directory contains `compose.yaml`, `.env` (credentials), `config.json` (server config), and `clash.yaml` (client config). Compose uses host networking and pins `ghcr.io/sagernet/sing-box:v1.14.4`; the default ports are 8388 TCP/UDP and 8443 TCP. Import `clash.yaml` into a Mihomo-based client such as Clash Verge, FlClash, or Clash Meta.
+
+Generated `.env`, `config.json`, and `clash.yaml` files use mode 600. They contain credentials: never commit them. The REALITY private key is not written to `clash.yaml`.
+
+## Troubleshooting
+
+- If the pinned image fails, change its tag in `compose.yaml` and run `docker compose up -d`.
+- To regenerate keys, delete `.env`, `config.json`, and `clash.yaml`, then rerun `npx my-singbox init`.
+- Run `npx my-singbox doctor` and address any `FAIL` results; `WARN` indicates a warning, such as legacy Compose.
+- If ports are unreachable, check the local firewall and cloud security group.
+- To stop and remove the deployment, run `docker compose down` in the deployment directory.
+
+## Legacy shell version (v1.1.0)
+
+See [v1.1.0](https://github.com/zht7063/my-singbox/releases/tag/v1.1.0) and the [shell-version branch](https://github.com/zht7063/my-singbox/tree/shell-version).
+
+## For agents
+
+See [deploy-sing-box-node](skills/deploy-sing-box-node/SKILL.md).

package/README_CN.md

@@ -0,0 +1,119 @@
+[English](README.md) | **简体中文**
+
+# My sing-box
+
+使用 Docker 中的 sing-box 部署 Shadowsocks 2022 和 VLESS-Reality-Vision 节点，并导出供 Mihomo 客户端使用的 `clash.yaml`。
+
+支持：仅限 Debian 和 Ubuntu VPS，x64 或 arm64。
+
+```bash
+curl -fsSLo install.sh https://raw.githubusercontent.com/zht7063/my-singbox/ts-version/install.sh
+sh install.sh && export PATH="$HOME/.local/node/bin:$PATH"
+```
+
+安装程序无需 sudo，将 Node >= 22 安装到 `~/.local/node`；如果 PATH 中已有 Node >= 22，则跳过安装。
+
+从 npm 安装命令行工具：
+
+```bash
+npm i -g my-singbox   # 之后运行 "my-singbox <cmd>"
+```
+
+也可以无需安装直接运行：`npx my-singbox <cmd>`。下文示例写作 `npx my-singbox <cmd>`；全局安装后可省略 `npx`。请在部署目录（例如 `/opt/sing-box`）中运行命令。
+
+## 使用
+
+要求：Node >= 22、Docker 及 Compose 插件、Docker socket 访问权限；UDP 检查可选用 `ss`。
+
+### init
+
+在可写的部署目录中（例如 `/opt/sing-box`）运行：
+
+```bash
+npx my-singbox init
+```
+
+`init` 运行 doctor，复制缺失的 `compose.yaml`，生成缺失的凭据和配置，启动并检查 sing-box，然后输出防火墙和客户端导入说明。重复运行时保留已有文件，且不会使用 sudo。
+
+### start
+
+```bash
+npx my-singbox start
+```
+
+`start` 运行 Docker Compose，检查容器是否持续运行、配置是否通过 `sing-box check`，以及配置的 TCP 端口是否接受本地连接。如果有 `ss`，还会检查 UDP 8388；自检失败时会输出容器日志。
+
+### isp-outbound
+
+```bash
+npx my-singbox isp-outbound --add
+npx my-singbox isp-outbound --remove
+```
+
+添加 ISP SOCKS5 出站（会询问代理地址和凭据）或移除它。不指定操作时显示菜单；`--yes` 或 `-y` 跳过重启确认，`--help` 显示选项。添加操作创建 13839 TCP/UDP 上的 `shadowsocks-isp` 和 18444 TCP 上的 `vless-reality-isp`，并在 `clash.yaml` 存在时加入其中。请在客户端重新导入该文件。命令将备份保存到 `.isp-backup`；移除时恢复添加 ISP 前的备份，因此受管理文件在此之后的修改不会保留在恢复后的文件中。命令不会修改防火墙规则。
+
+### doctor
+
+```bash
+npx my-singbox doctor
+```
+
+只读检查 Node 版本、Linux 和 libc、架构、Docker Compose 及 Docker socket 访问权限。每项结果显示 `OK`、`WARN` 或 `FAIL`；存在失败项时返回非零退出状态。
+
+| 命令 | 用途 |
+| --- | --- |
+| `init` | 准备缺失的文件并启动 sing-box。 |
+| `gen-keys` | 生成 `.env` 凭据；单独运行时需要在环境中设置 `SING_BOX_VERSION`（镜像标签）。 |
+| `gen-config` | 生成服务端配置。 |
+| `conf-clash` | 生成客户端配置。 |
+| `start` | 启动 sing-box 并执行自检。 |
+| `isp-outbound` | 添加或移除 ISP 出站。 |
+| `doctor` | 检查运行条件。 |
+
+使用 `npx my-singbox --help` 或 `-h` 查看命令帮助。手动设置时，先把 `compose.yaml` 复制到部署目录，然后运行：
+
+```bash
+SING_BOX_VERSION=v1.14.4 npx my-singbox gen-keys
+npx my-singbox gen-config
+npx my-singbox conf-clash
+npx my-singbox start
+```
+
+## 防火墙和端口
+
+在本机防火墙和云安全组中开放 8388/tcp、8388/udp 和 8443/tcp。使用 ISP 出站时，还需开放 13839/tcp、13839/udp 和 18444/tcp。工具不会修改防火墙规则。
+
+## 安装 Docker
+
+```bash
+curl -fsSL https://get.docker.com | sudo sh
+sudo usermod -aG docker "$USER"
+```
+
+退出并重新登录，或运行 `newgrp docker`。Docker 组成员权限等同于 root。
+
+## 不支持的系统
+
+仅支持 Debian 和 Ubuntu；其他发行版均不受支持。`install.sh` 和 doctor 在 Alpine/musl、glibc 低于 2.28 以及 x64、arm64 以外的 CPU 架构上也会报错退出。请改用 [shell 版本 v1.1.0](https://github.com/zht7063/my-singbox/releases/tag/v1.1.0)（分支 [`shell-version`](https://github.com/zht7063/my-singbox/tree/shell-version)）。
+
+## 文件和配置
+
+部署目录包含 `compose.yaml`、`.env`（凭据）、`config.json`（服务端配置）和 `clash.yaml`（客户端配置）。Compose 使用宿主机网络，镜像固定为 `ghcr.io/sagernet/sing-box:v1.14.4`；默认端口为 8388 TCP/UDP 和 8443 TCP。将 `clash.yaml` 导入基于 Mihomo 的客户端，例如 Clash Verge、FlClash 或 Clash Meta。
+
+生成的 `.env`、`config.json` 和 `clash.yaml` 文件权限为 600。这些文件包含凭据，切勿提交到版本库。REALITY 私钥不会写入 `clash.yaml`。
+
+## 故障排查
+
+- 如果固定版本的镜像无法使用，请修改 `compose.yaml` 中的标签并运行 `docker compose up -d`。
+- 如需重新生成密钥，删除 `.env`、`config.json` 和 `clash.yaml`，然后重新运行 `npx my-singbox init`。
+- 运行 `npx my-singbox doctor` 并处理所有 `FAIL` 项；`WARN` 表示警告，例如使用旧版 Compose。
+- 如果端口无法访问，请检查本机防火墙和云安全组。
+- 如需停止并移除部署，在部署目录中运行 `docker compose down`。
+
+## 旧版 shell（v1.1.0）
+
+参见 [v1.1.0](https://github.com/zht7063/my-singbox/releases/tag/v1.1.0) 和 [shell-version 分支](https://github.com/zht7063/my-singbox/tree/shell-version)。
+
+## 给 agent
+
+参见 [deploy-sing-box-node](skills/deploy-sing-box-node/SKILL.md)。

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,17 @@
+# Third-party notices
+
+yaml 2.9.1 — ISC license
+
+Copyright Eemeli Aro <eemeli@gmail.com>
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.

package/compose.yaml

@@ -0,0 +1,17 @@
+services:
+  sing-box:
+    # Pinned to v1.14.4 (index digest sha256:0788ffbddab2c68a99a2dd4780bbc50902f159af6f589df3ee74a8389d278279). To upgrade, change the tag and the CI pin together.
+    image: ghcr.io/sagernet/sing-box:v1.14.4
+    container_name: sing-box
+    restart: unless-stopped
+    network_mode: host
+    volumes:
+      - ./config.json:/etc/sing-box/config.json:ro
+    command: -c /etc/sing-box/config.json run
+
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
+