Initialize Clash Web source and deployment documentation

docs/development.md

@@ -0,0 +1,121 @@
+# 开发与测试
+
+## 环境
+
+- Go 1.24+。
+- Node.js 22.12+ 或 24+，npm。
+- Python 3；Linux amd64 打包脚本的安全解压校验需要 Python 3.12+。
+- Linux；正式代理服务与开发环境分开。
+
+依赖版本由 go.mod、go.sum 和 web/package-lock.json 固定。Go 模块目录遵循开发机的 go env 配置。
+
+## 首次准备
+
+在项目根目录执行：
+
+```bash
+make build
+make assets
+```
+
+make build 安装锁定的前端依赖、生成 web/dist，再构建 bin/clashweb；静态 Web 资源嵌入 Go 程序。make assets 下载指定 Mihomo 稳定版和大陆 MRS 规则，分别保存到 bin/mihomo 和 data/mihomo/rules。
+
+资源已有时可复用：
+
+```bash
+cd web
+npm run build
+cd ..
+CGO_ENABLED=0 go build -trimpath -ldflags='-s -w' -o bin/clashweb ./cmd/clashweb
+```
+
+Go 构建与测试依赖 web/dist 存在，首次克隆应先构建前端。前端构建完成后再执行 Go 构建，避免嵌入尚未生成的资源。
+
+## 本地运行
+
+终端一，生成配置并启动内核：
+
+```bash
+./bin/clashweb --mihomo ./bin/mihomo --init
+./bin/mihomo -d ./data/mihomo -f ./data/mihomo/config.yaml
+```
+
+终端二，启动管理服务：
+
+```bash
+./bin/clashweb --mihomo ./bin/mihomo
+```
+
+访问 http://127.0.0.1:8080。首次设置令牌在启动日志中显示，管理员密码为 12–72 字节。已初始化的数据目录使用原管理员密码登录。
+
+默认混合代理为 127.0.0.1:7890，DNS 为 127.0.0.1:1053，Mihomo 控制接口为 127.0.0.1:9090。开发时保持 TUN 关闭；IPv4 转发、防火墙和网关配置在目标 VM 上准备。
+
+前端热更新时，保持 Go 后端运行，并在另一终端执行：
+
+```bash
+cd web
+npm run dev
+```
+
+Vite 将 /api 转发至 http://127.0.0.1:8080。远程开发可用 SSH 转发访问管理服务：
+
+```bash
+ssh -N -L 8080:127.0.0.1:8080 USER@DEV_HOST
+```
+
+停止时在管理服务和内核终端分别按 Ctrl+C。本地 data/ 目录保留管理员、订阅和设置。
+
+## 测试
+
+前端构建已完成时可直接执行：
+
+```bash
+go test -race ./...
+go vet ./...
+cd web
+npm run test
+cd ..
+```
+
+真实内核集成测试：
+
+```bash
+CLASHWEB_TEST_MIHOMO_BIN="$PWD/bin/mihomo" \
+CLASHWEB_TEST_RULES_DIR="$PWD/data/mihomo/rules" \
+go test -race ./...
+```
+
+浏览器测试首次需要安装 Chromium：
+
+```bash
+cd web
+npx playwright install chromium
+cd ..
+python3 scripts/test-e2e.py
+```
+
+E2E 使用临时数据库、本地订阅夹具、真实后端和 Mihomo；管理服务监听 127.0.0.1:18080，需要 9090/7890/1053 空闲。检测到端口占用时终止，结束后清理测试进程和临时数据库。常用网站响应在浏览器测试中使用夹具。
+
+截图写入 .cache/screenshots，测试报告写入 web/test-results，均不提交到 Git。无需重装依赖时，直接使用以上命令；make test、make integration、make e2e 会先重新准备前端依赖。
+
+## 配置与提交范围
+
+- bin/：本地生成的管理程序和下载的内核。
+- data/：SQLite、订阅、控制密钥、内核配置和规则。
+- web/dist/：嵌入 Go 程序的前端输出。
+- web/node_modules/：前端开发依赖。
+- .cache/、测试报告和压缩包：过程或分发产物。
+
+这些目录和文件由 .gitignore 排除。只提交源码、锁文件、测试、部署脚本和维护文档。
+
+## 打包
+
+在 Linux amd64 构建环境执行：
+
+```bash
+GOOS=linux GOARCH=amd64 GOAMD64=v1 CGO_ENABLED=0 \
+go build -trimpath -ldflags='-s -w' -o bin/clashweb ./cmd/clashweb
+python3 scripts/package.py
+```
+
+脚本只使用现有程序与规则生成完整安装包和管理更新包，附文件清单和 SHA-256，执行解压校验与隔离初始化，不包含开发数据库或订阅。分发包通过 Gitea Release 或其他文件渠道传递，不作为源码提交。