docs: refresh bilingual readmes
- make Chinese the default README\n- streamline installation and usage guidance\n- align platform, IPv6, storage, and CLI documentation
This commit is contained in:
bluebluesoda committed
1 parent
8ab4d396d9
commit
50496f9367
3 files changed
+177
-166
No files matched your search
+108
@@ -0,0 +1,108 @@
|
||||
# Vpsmgr Lite
|
||||
|
||||
A lightweight Incus container hosting panel for small VPS instances and low-memory hosts.
|
||||
|
||||
> **Security warning:** The “VMs” created by this project are LXC containers, not virtual machines. Container isolation is weaker than KVM/QEMU. A container escape or kernel vulnerability could affect the host and other tenants. Do not run untrusted or high-security workloads on a shared host.
|
||||
|
||||
[简体中文](README.md) · [Documentation](docs/README.md)
|
||||
|
||||
## Features
|
||||
|
||||
- One Debian 13 container per user
|
||||
- Web controls for start, stop, restart, and reinstall
|
||||
- IPv4 NAT, SSH forwarding, and user port ranges
|
||||
- Traefik HTTP/HTTPS domain proxying
|
||||
- Optional IPv6 pass-through, with prefix and address-pool modes
|
||||
- CPU, memory, disk, and monthly bandwidth quotas
|
||||
- Admin panel, domain management, IPv6 pool management, and audit logs
|
||||
- One small Go binary and a slim container image
|
||||
|
||||
## Installation
|
||||
|
||||
Ubuntu 22.04, 24.04, or 26.04 is recommended. Debian 12 and 13 are also supported, but installing ZFS on Debian typically requires an additional DKMS build and can take considerably longer.
|
||||
|
||||
Recommended minimum: 1 CPU core, 1.5 GB RAM, 10 GB of free disk space, and root access. Both amd64 and arm64 are supported; testing has focused mainly on amd64.
|
||||
|
||||
```sh
|
||||
git clone https://github.com/bluebluesoda/vpsmgr.git
|
||||
cd vpsmgr
|
||||
sudo ./install.sh # download the latest prebuilt binary
|
||||
# sudo ./install.sh --local-build # always build from this checkout
|
||||
# sudo ./install.sh --update # update an existing install from the release
|
||||
```
|
||||
|
||||
The installer first downloads the prebuilt binary from GitHub Releases. If that fails, it falls back to a local build. `--local-build` always rebuilds from source. If `--update` cannot download the release, the existing binary is left untouched.
|
||||
|
||||
ZFS is the default storage backend. For disposable test machines, you can explicitly choose the `dir` backend. It does not provide ZFS quotas, snapshots, or cloning:
|
||||
|
||||
```sh
|
||||
sudo VPSMGR_STORAGE=dir ./install.sh
|
||||
```
|
||||
|
||||
### IPv6
|
||||
|
||||
IPv6 pass-through is disabled by default. Interactive installation offers three choices:
|
||||
|
||||
- **Prefix mode:** the provider routes an entire IPv6 prefix to the host
|
||||
- **Address-pool mode:** the provider supplies separate IPv6 addresses, which an administrator adds in the admin panel
|
||||
- **Disabled:** IPv4 only
|
||||
|
||||
To check IPv6 reachability before installation:
|
||||
|
||||
```sh
|
||||
bash check-ipv6-support.sh
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
```sh
|
||||
vps add <name> [--cpu N] [--mem NG] [--disk NG] [--bandwidth N]
|
||||
vps quota <name> [--cpu N] [--mem NG] [--disk NG] [--bandwidth N]
|
||||
vps list [name]
|
||||
vps power <name> start|stop|restart
|
||||
vps passwd <name>
|
||||
vps del <name>
|
||||
vps panel-url
|
||||
vps admin-passwd
|
||||
vps config list|set|help
|
||||
```
|
||||
|
||||
The default allocation is 1 CPU core, 1 GB of RAM, and 10 GB of disk. CPU values may be whole cores or a fraction from `0.1` to `0.9`; disk capacity can only be increased. Generated passwords are shown once.
|
||||
|
||||
Bandwidth quotas are monthly GiB totals for upload and download combined. Containers over quota are rate-limited to 1 Mbps in both directions without a restart.
|
||||
|
||||
Users can define an init script in the panel. It runs as root inside the container after reinstall, with output written to `/var/log/vpsmgr-init.log`.
|
||||
|
||||
## Additional Images
|
||||
|
||||
Debian 13 is the default image. To offer AlmaLinux 9 or Rocky Linux 9 during reinstall, build one once:
|
||||
|
||||
```sh
|
||||
sudo bash scripts/60-rhel-image.sh # AlmaLinux 9
|
||||
sudo bash scripts/60-rhel-image.sh rocky # Rocky Linux 9
|
||||
```
|
||||
|
||||
The image builder is not run by `install.sh`, keeping the default installation small.
|
||||
|
||||
## Configuration and Removal
|
||||
|
||||
The configuration file is `/etc/vpsmgr/config.yaml`. Prefer the validated CLI over editing it directly:
|
||||
|
||||
```sh
|
||||
vps config list
|
||||
vps config help
|
||||
vps config set <key> <value>
|
||||
```
|
||||
|
||||
```sh
|
||||
sudo ./uninstall.sh # remove software, keep config, database, and containers
|
||||
sudo ./uninstall.sh --purge # also remove config, database, containers, storage, and Incus
|
||||
```
|
||||
|
||||
See the [documentation index](docs/README.md) for technical details.
|
||||
|
||||
## Screenshots
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -1,127 +1,108 @@
|
||||
# Vpsmgr Lite
|
||||
|
||||
**Warning ⚠️ The "VMs" this project creates are LXC containers, not real
|
||||
virtual machines. Their isolation and security are far weaker than other
|
||||
virtualization approaches (KVM/QEMU, etc.). A kernel-level or container escape
|
||||
would affect the host and every tenant. Security risk is yours to accept — do
|
||||
not run untrusted or high-security workloads on a shared host.**
|
||||
轻量级 Incus 容器托管面板，适合小型 VPS 和低配主机。
|
||||
|
||||
[简体中文](README.zh-CN.md) · [Docs](docs/README.md)
|
||||
> **安全警告**：这里的“虚拟机”是 LXC 容器，不是真正的虚拟机。容器隔离性弱于 KVM/QEMU。容器逃逸或内核漏洞可能影响宿主机和其他租户。不要在共享主机上运行不受信任或高安全要求的工作负载。
|
||||
|
||||
A toy LXC hosting panel for small machines (≤ 4 GB RAM, small VPS): one Debian
|
||||
13 container per user, managed from a web panel (start/stop/restart/reinstall),
|
||||
with automatic NAT4 port forwarding and 80/443 per-domain proxying by Traefik.
|
||||
Optional IPv6 pass-through (no NAT). The panel is a single small Go binary and
|
||||
the container image stays slim — storage and memory are treated as scarce.
|
||||
[English](README.en.md) · [文档](docs/README.md)
|
||||
|
||||
Install notes: shared IPv4 inbound is always ON by default (flip it later with
|
||||
`vps config set net.v4_forward true|false`); the only network choice the
|
||||
installer asks for is the container subnet's second octet. Port 25 (SMTP) is
|
||||
always blocked for containers, both directions — anti-spam, no toggle.
|
||||
## 功能
|
||||
|
||||
## Install
|
||||
- 每个用户一个 Debian 13 容器
|
||||
- Web 面板管理：启动、停止、重启、重装
|
||||
- IPv4 NAT、SSH 和端口转发
|
||||
- Traefik 代理 HTTP/HTTPS 域名
|
||||
- 可选 IPv6 直通：前缀模式或地址池模式，无 NAT
|
||||
- CPU、内存、磁盘和月度流量配额
|
||||
- 管理员面板、域名管理、IPv6 地址池和审计日志
|
||||
- 单个 Go 二进制，容器镜像保持精简
|
||||
|
||||
**Minimum: Debian 12/13 or Ubuntu 22.04/24.04/26.04 (bare metal or KVM), 1 core, 1.5G RAM, 10G free disk, and root access**
|
||||
## 安装
|
||||
|
||||
Both amd64 and arm64 are supported; testing has primarily been done on amd64.
|
||||
推荐使用 Ubuntu 22.04、24.04 或 26.04。也支持 Debian 12/13，但 Debian 安装 ZFS 时通常需要额外编译 DKMS 模块，安装时间可能明显更长。
|
||||
|
||||
```
|
||||
git clone https://github.com/bluebluesoda/vpsmgr.git && cd vpsmgr
|
||||
sudo ./install.sh # install the stable prebuilt binary
|
||||
#sudo ./install.sh --local-build # force a local build from source
|
||||
最低建议：1 核、1.5 GB 内存、10 GB 可用磁盘空间，以及 root 权限。amd64 和 arm64 均支持，主要在 amd64 上测试。
|
||||
|
||||
```sh
|
||||
git clone https://github.com/bluebluesoda/vpsmgr.git
|
||||
cd vpsmgr
|
||||
sudo ./install.sh # 下载最新预编译版本
|
||||
# sudo ./install.sh --local-build # 强制从当前源码编译
|
||||
# sudo ./install.sh --update # 更新现有安装的预编译版本
|
||||
```
|
||||
|
||||
The installer configures the Zabbly Incus LTS repository and installs Incus 7
|
||||
LTS (Debian packages — the same repo serves Ubuntu, so the panel is portable
|
||||
across both).
|
||||
默认安装会先下载 GitHub Release 中的预编译二进制；下载失败时会回退到本地编译。`--local-build` 总是重新编译，`--update` 下载失败时保留现有二进制。
|
||||
|
||||
To enable IPv6 pass-through, make sure the host has been assigned an entire
|
||||
routed prefix. Ask your provider, or use the check script in this repository
|
||||
for an informal test.
|
||||
安装器会配置 Zabbly Incus 7 LTS 软件源，并默认使用 ZFS 存储。测试环境可显式使用 `VPSMGR_STORAGE=dir`，但该模式没有 ZFS 的配额、快照和克隆能力：
|
||||
|
||||
**Be sure the entire IPv6 prefix works before installing with IPv6 support.**
|
||||
|
||||
```
|
||||
bash check-ipv6-support.sh # IPv6 test script
|
||||
```sh
|
||||
sudo VPSMGR_STORAGE=dir ./install.sh
|
||||
```
|
||||
|
||||
Run `vps panel-url` after installation to get the full panel address —
|
||||
`https://<IP>:<port>/<random-path>` (the port is a random free one in
|
||||
2000-9999). This random path is the panel's only entry point.
|
||||
### IPv6
|
||||
|
||||
## Optional: extra OS images
|
||||
IPv6 直通默认关闭。交互式安装会询问是否启用，并根据网络条件提供以下模式：
|
||||
|
||||
The default is Debian 13. To let users reinstall their container with a
|
||||
RHEL-family system, run (once, as root) the optional image builder — it is NOT
|
||||
run by `install.sh` so small boxes stay lean:
|
||||
- **前缀模式**：服务商将完整 IPv6 前缀路由到宿主机
|
||||
- **地址池模式**：服务商提供多个可用的独立 IPv6 地址，在管理员面板中添加
|
||||
- **关闭**：仅使用 IPv4
|
||||
|
||||
```
|
||||
sudo bash scripts/60-rhel-image.sh # Alma 9
|
||||
sudo bash scripts/60-rhel-image.sh rocky # Rocky 9
|
||||
需要检查 IPv6 时，可先运行：
|
||||
|
||||
```sh
|
||||
bash check-ipv6-support.sh
|
||||
```
|
||||
|
||||
Reinstall then offers the built images as a choice (always, even with only the
|
||||
default). The image is slimmed and the base image deleted, same as the Debian
|
||||
one.
|
||||
## 使用
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
vps add <name> [--cpu N] [--mem NG] [--disk NG] # default 1 core / 1G / 10G; cpu = whole cores (>=1) or a decimal 0.1..0.9; password is auto-generated and shown once
|
||||
vps quota <name> [--cpu N] [--mem N] [--disk NG] # disk can only grow
|
||||
vps passwd <name> # reissue user panel password (shown once)
|
||||
vps list [name] # all users, or one user's detail
|
||||
```sh
|
||||
vps add <name> [--cpu N] [--mem NG] [--disk NG] [--bandwidth N]
|
||||
vps quota <name> [--cpu N] [--mem NG] [--disk NG] [--bandwidth N]
|
||||
vps list [name]
|
||||
vps power <name> start|stop|restart
|
||||
vps passwd <name>
|
||||
vps del <name>
|
||||
vps panel-url
|
||||
vps config set net.v4_forward true|false # shared IPv4 inbound: false = IPv6-only containers
|
||||
vps admin-passwd
|
||||
vps config list|set|help
|
||||
```
|
||||
|
||||
Users can set a custom **init script** in their panel — it runs as root inside
|
||||
their container after a reinstall (output at `/var/log/vpsmgr-init.log`), for
|
||||
cloud-provider-style first-boot automation.
|
||||
默认配额为 1 核、1 GB 内存和 10 GB 磁盘。CPU 支持整数核心，或 `0.1` 到 `0.9` 的小数核心；磁盘只能扩容。密码只显示一次。
|
||||
|
||||
Admins can set a per-user monthly **bandwidth quota** (GiB, upload + download);
|
||||
a container that exceeds it is rate-limited to **1Mbps** both directions. The
|
||||
limit is applied live via Incus (tc qdiscs) — no container restart.
|
||||
月度流量配额单位为 GiB，统计上传和下载总量。超额后容器双向限速为 1 Mbps，无需重启。
|
||||
|
||||
Domains can opt into **PROXY protocol v2** (the 443 TLS passthrough reports the
|
||||
visitor IP to the backend, which must support it; HTTP/80 keeps normal
|
||||
`X-Forwarded-For` headers). An admin **domain management** page lists every
|
||||
domain with its owner and last-modified time (UTC, shown in the browser's
|
||||
timezone) and can toggle the setting or delete domains.
|
||||
用户可以在面板设置初始化脚本。重装后脚本会在容器内以 root 运行，日志位于 `/var/log/vpsmgr-init.log`。
|
||||
|
||||
An **audit log** records resource-heavy user actions — power, reinstall, root
|
||||
password reset, domain config changes. Rows are attributed to the acting
|
||||
username, or `000+<username>` when an admin acts on that user's resources. The
|
||||
admin audit page loads it in 500-row chunks with infinite scroll; the latest
|
||||
5000 entries are kept.
|
||||
## 额外镜像
|
||||
|
||||
## Config
|
||||
默认镜像是 Debian 13。需要 AlmaLinux 9 或 Rocky Linux 9 时，可手动构建一次：
|
||||
|
||||
`/etc/vpsmgr/config.yaml` (auto-generated at install) — **the defaults are not
|
||||
meant to be changed**. The sanctioned interface is `vps config list/set/help`,
|
||||
which validates every change and refuses immutable fields. Reference:
|
||||
[docs/configuration.md](docs/configuration.md).
|
||||
|
||||
## Uninstall
|
||||
|
||||
```
|
||||
sudo ./uninstall.sh # remove software, keep config/db/containers
|
||||
sudo ./uninstall.sh --purge # also delete config/db, containers, pool, Incus
|
||||
```sh
|
||||
sudo bash scripts/60-rhel-image.sh # AlmaLinux 9
|
||||
sudo bash scripts/60-rhel-image.sh rocky # Rocky Linux 9
|
||||
```
|
||||
|
||||
## Documentation
|
||||
该脚本不会由 `install.sh` 自动执行，以减少小型主机的安装负担。
|
||||
|
||||
Technical detail lives in `docs/` (English): [index](docs/README.md), plus
|
||||
[`AGENTS.md`](AGENTS.md) for AI coding agents.
|
||||
## 配置与卸载
|
||||
|
||||
## Screenshots
|
||||
配置文件为 `/etc/vpsmgr/config.yaml`。建议使用以下命令修改，而不是直接编辑文件：
|
||||
|
||||
Admin panel:
|
||||
```sh
|
||||
vps config list
|
||||
vps config help
|
||||
vps config set <key> <value>
|
||||
```
|
||||
|
||||
|
||||
```sh
|
||||
sudo ./uninstall.sh # 删除软件，保留配置、数据库和容器
|
||||
sudo ./uninstall.sh --purge # 额外删除配置、数据库、容器、存储池和 Incus
|
||||
```
|
||||
|
||||
User panel:
|
||||
更多内容见 [文档索引](docs/README.md)。
|
||||
|
||||
|
||||
## 截图
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -1,78 +0,0 @@
|
||||
# Vpsmgr Lite
|
||||
**警告 ⚠️ 本项目创建的"虚拟机"是 LXC 容器，并非真正的虚拟机，其隔离性与安全性远低于 KVM/QEMU 等其他虚拟化方式。一旦发生内核级或容器逃逸，将影响宿主机及所有租户。安全风险自理——请勿在共享宿主机上运行不受信任或高安全要求的工作负载。**
|
||||
|
||||
[English](README.md) · [文档](docs/README.md)
|
||||
|
||||
面向小型机器（≤ 4G 内存、小型 VPS）的玩具级 LXC 托管面板：每用户一台 Debian 13，用户通过 Web 面板管理机器（开机/关机/重启/重装），自动 NAT4 端口转发，80/443 按域名由 Traefik 转发。可选 IPv6 直通（无 NAT）。面板是一个很小的 Go 单二进制，容器镜像保持精简——存储和内存都视作稀缺资源。
|
||||
|
||||
安装提示：共享 IPv4 入站默认开启，不再询问（可在之后用 `vps config set net.v4_forward true|false` 切换）；安装时唯一可自定义的网络项是容器子网的第二段八位组。容器 25 端口（SMTP）双向永久封禁（反垃圾邮件，无开关）。
|
||||
|
||||
## 安装
|
||||
|
||||
**最低要求：Ubuntu 24.04（物理机或 KVM）1 核心 1.5G 内存 10G 磁盘空闲 root**
|
||||
|
||||
amd64/arm64 均可，主要在amd64上进行了测试
|
||||
|
||||
```
|
||||
git clone https://github.com/bluebluesoda/vpsmgr.git && cd vpsmgr
|
||||
sudo ./install.sh # 安装稳定版预编译二进制
|
||||
#sudo ./install.sh --local-build # 强制本地编译
|
||||
#sudo ./install.sh --update # 强制重新下载预编译二进制（覆盖已安装的）
|
||||
```
|
||||
|
||||
**如需启用IPv6直通，请确保宿主机获得整段Route**，可以询问服务商，或者使用仓库中的检查脚本进行不严谨的测试。
|
||||
**务必在测试v6整段可用后再尝试以v6支持进行安装**
|
||||
```
|
||||
bash check-ipv6-support.sh #v6测试脚本
|
||||
```
|
||||
|
||||
|
||||
装完运行 `vps panel-url` 查看完整面板地址——`https://<IP>:<端口>/<随机路径>`(端口为 2000-9999 中随机选取的空闲端口)。该随机路径是面板唯一入口。
|
||||
|
||||
## 可选：额外系统镜像
|
||||
|
||||
默认系统为 Debian 13。想让用户重装容器时选 RHEL 系系统，可以（以 root）运行一次可选的镜像构建脚本——它不会在 `install.sh` 里自动执行，小型机器保持精简：
|
||||
|
||||
```
|
||||
sudo bash scripts/60-rhel-image.sh # Alma 9
|
||||
sudo bash scripts/60-rhel-image.sh rocky # Rocky 9
|
||||
```
|
||||
|
||||
之后重装弹窗会列出这些镜像供选择（即使只有默认镜像也会让用户选）。镜像构建与 Debian 一致：精简缓存、发布后删除基础镜像。
|
||||
|
||||
## 使用
|
||||
|
||||
```
|
||||
vps add <name> [--cpu N] [--mem NG] [--disk NG] # 默认 1核/1G/10G；cpu 可为整数核（≥1）或 0.1~0.9 小数；密码自动生成，仅显示一次
|
||||
vps quota <name> [--cpu N] [--mem N] [--disk NG] # 磁盘只许扩
|
||||
vps passwd <name> # 重发用户面板密码（仅显示一次）
|
||||
vps list [name] # 全部用户，或单个详情
|
||||
vps power <name> start|stop|restart
|
||||
vps del <name>
|
||||
vps panel-url
|
||||
vps config set net.v4_forward true|false # 共享 IPv4 入站开关：false = 容器仅 IPv6
|
||||
```
|
||||
|
||||
用户可在面板中设置自定义**初始化脚本**——重装后在容器内以 root 自动运行（输出在容器内 /var/log/vpsmgr-init.log），用于云厂商式的首次引导自动化。
|
||||
|
||||
管理员可设置每用户的**月度流量配额**（GiB，上传+下载）；超限后容器上下行各限速 **1Mbps**。限速由 Incus 实时应用（tc qdisc），无需重启容器。
|
||||
|
||||
域名可选用 **PROXY protocol v2**（443 TLS 直通向后端汇报访客 IP，后端需适配；HTTP/80 保持常规 X-Forwarded-For header）。管理员有**域名管理**页面：列出所有域名及其所属用户、最后修改时间（UTC，按浏览器时区显示），可修改该设置或删除域名。
|
||||
|
||||
**审计日志**记录耗资源的用户操作——开关机、重装、重置 root 密码、域名配置变更。操作者标记为操作用户名；管理员对某用户资源操作时标记为 `000+<用户名>`。管理员审计页分片加载（每片 500 条、滚动到底自动加载），保留最近 5000 条。
|
||||
|
||||
## 配置
|
||||
|
||||
`/etc/vpsmgr/config.yaml`（安装时自动生成）——**默认配置不建议修改**。正规入口是 `vps config list/set/help`，会校验每次改动并拒绝不可变字段。参考：[docs/configuration.md](docs/configuration.md)。
|
||||
|
||||
## 卸载
|
||||
|
||||
```
|
||||
sudo ./uninstall.sh # 卸载软件，保留 config/db/容器
|
||||
sudo ./uninstall.sh --purge # 连 config/db、容器、存储池、Incus 一起删
|
||||
```
|
||||
|
||||
## 文档
|
||||
|
||||
技术细节在 `docs/`（英文）：[索引](docs/README.md)；另有面向 AI 编程代理的 [`AGENTS.md`](AGENTS.md)。
|
||||
|
||||
Reference in new issue
Block a user