NextShell Cloud Sync Server

轻量自部署的云同步服务端，让同一用户在多台设备间共享连接、SSH 密钥和代理配置。

特性

• 单二进制，零外部依赖（内嵌 SQLite）
• 强制 HTTPS，Basic Auth 认证
• Workspace 自动创建，密码 bcrypt 加密存储
• 资源引用完整性检查（删除被引用的 SSH Key / Proxy 返回 409）
• 删除墓碑机制，确保跨设备同步删除
• 版本号单调递增，支持增量检测

快速开始

构建

cd server
go build -o nshellserver .

生成 TLS 证书

生产环境建议使用 Let's Encrypt 等 CA 签发的证书。本地测试可用自签名证书：

openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem \
  -days 365 -nodes -subj '/CN=localhost'

启动

./nshellserver serve --cert cert.pem --key key.pem

默认日志级别是 info。需要查看更多接入和请求细节时，可以显式开启 debug：

./nshellserver serve --cert cert.pem --key key.pem --log-level debug

开发模式也可以直接运行：

./nshellserver serve --dev

--dev 会在当前运行目录查找 nshell-key.pem 和 nshell-crt.pem。如果两个文件都不存在，程序会直接调用系统 openssl 生成并复用这对自签名证书；如果只存在其中一个，则启动失败。--dev 不能与 --cert 或 --key 混用。

自托管并由外部反向代理终止 HTTPS 时，可以直接监听 HTTP：

./nshellserver serve --self-host

这会强制服务监听 127.0.0.1，不加载证书，适合只让本机反向代理转发。

如果确实需要直接对外暴露 HTTP 监听，可以显式运行：

./nshellserver serve --self-host --public

这会打印不安全警告，并把监听地址强制改为 0.0.0.0。--public 只能与 --self-host 一起使用。--self-host 不能与 --cert、--key 或 --dev 混用。

直接执行 ./nshellserver 只会显示帮助信息；旧用法 ./nshellserver --dev 不再支持。

配置项

CLI 参数优先于环境变量。以上参数均属于 serve 子命令，例如 ./nshellserver serve --addr :9443 --dev。

当 --log-level 或 NSHELL_LOG_LEVEL 的值非法时，程序会回退到 info，并打印一条 warning 日志提示。

验证

curl -k -X POST https://localhost:8443/api/v1/sync/workspace/status \
  -u "myworkspace:mypassword" \
  -H "Content-Type: application/json" \
  -d '{}'

成功返回：

{"ok": true, "workspace": "myworkspace", "version": 0, "serverTime": "..."}

项目结构

server/
├── main.go                        # 入口：执行 cobra 根命令
├── cmd/
│   ├── root.go                    # 根命令与帮助行为
│   └── serve.go                   # serve 子命令与 flag 绑定
├── internal/
│   ├── config/config.go           # 配置默认值与环境变量补全
│   ├── db/
│   │   ├── db.go                  # SQLite 连接、pragma、迁移
│   │   └── store.go               # 数据层 CRUD
│   ├── handler/
│   │   ├── handler.go             # Handler + JSON 工具函数
│   │   ├── middleware.go          # Basic Auth + Body Limit
│   │   ├── workspace.go          # workspace/status
│   │   ├── pull.go               # pull
│   │   ├── connection.go         # connections upsert/delete
│   │   ├── sshkey.go             # ssh-keys upsert/delete
│   │   └── proxy.go              # proxies upsert/delete
│   ├── model/model.go            # 请求/响应结构体
│   └── server/server.go          # 服务启动、TLS/self-host、graceful shutdown

依赖