diff --git a/docs/en/guide/oneclickvirt/oneclickvirt_custom.md b/docs/en/guide/oneclickvirt/oneclickvirt_custom.md index 182103f8ed..2d114c4bd3 100644 --- a/docs/en/guide/oneclickvirt/oneclickvirt_custom.md +++ b/docs/en/guide/oneclickvirt/oneclickvirt_custom.md @@ -2,4 +2,243 @@ outline: deep --- -Occupancy pending construction \ No newline at end of file +## Configuration File + +The default settings are sufficient for light usage. If advanced customization is needed, you need to modify the configuration file or make modifications in the admin interface after initialization. + +https://github.com/oneclickvirt/oneclickvirt/blob/main/server/config.yaml + +Here is the complete initialization configuration file. The specific configuration items will be explained below: + +### auth Authentication Configuration + +```yaml +auth: + email-password: "" + email-smtp-host: "" + email-smtp-port: "3306" + email-username: root + enable-email: false + enable-oauth2: false + enable-public-registration: false + enable-qq: false + enable-telegram: false + qq-app-id: "" + qq-app-key: "" + telegram-bot-token: "" + frontend-url: "" +``` + +Configuration items for the authentication module, used to control user login and registration methods and third-party login integration. + +- `email-password`: Authentication password for email service, used for identity verification when sending emails via SMTP +- `email-smtp-host`: SMTP server address, such as `smtp.gmail.com` +- `email-smtp-port`: SMTP server port, common ports are `25`, `465` (SSL), `587` (TLS) +- `email-username`: SMTP server login username, usually the complete email address +- `enable-email`: Whether to enable email login functionality +- `enable-oauth2`: Whether to enable OAuth2 third-party login functionality +- `enable-public-registration`: Whether to allow public registration; when disabled, only administrators can create accounts +- `enable-qq`: Whether to enable QQ login +- `enable-telegram`: Whether to enable Telegram login +- `qq-app-id`: App ID applied for from QQ Connect platform +- `qq-app-key`: App Key applied for from QQ Connect platform +- `telegram-bot-token`: API Token for Telegram Bot +- `frontend-url`: Frontend access address, must include protocol header (`http://` or `https://`), trailing slash is optional. OAuth2 callback address depends on this configuration + +### captcha Verification Code Configuration + +```yaml +captcha: + enabled: true + expire-time: 300 + height: 40 + length: 4 + width: 120 +``` + +Configuration for generating and verifying graphical verification codes, used for security verification on frontend login and registration pages. + +- `enabled`: Whether to enable verification code functionality +- `expire-time`: Verification code expiration time, in seconds +- `height`: Verification code image height, in pixels +- `length`: Verification code character length +- `width`: Verification code image width, in pixels + +### cdn Content Delivery Network Configuration + +```yaml +cdn: + base-endpoint: https://cdn.spiritlhl.net/ + endpoints: + - https://cdn0.spiritlhl.top/ + - http://cdn3.spiritlhl.net/ + - http://cdn1.spiritlhl.net/ + - http://cdn2.spiritlhl.net/ +``` + +CDN acceleration node configuration used when downloading system images. + +- `base-endpoint`: Primary CDN node address, used with priority +- `endpoints`: Backup CDN node list, retried in order. The system will automatically select available nodes for image downloads + +Generally, this configuration does not need to be modified. Preloaded system images are all hosted in the organization's repository, and the default CDN nodes already provide good download acceleration. + +### mysql Database Configuration + +```yaml +mysql: + auto-create: true + config: charset=utf8mb4&parseTime=True&loc=Local + db-name: oneclickvirt + engine: InnoDB + log-mode: error + log-zap: false + max-idle-conns: 10 + max-lifetime: 3600 + max-open-conns: 100 + password: "" + path: "" + port: "" + prefix: "" + singular: false + username: root +``` + +MySQL database connection and behavior configuration. Initialization judgment logic: when both `path` and `port` are empty, the system considers initialization is needed, and the target database must be an empty database at this time. + +- `auto-create`: Whether to automatically create the database (if it doesn't exist) +- `config`: Database connection parameters, including character set, time parsing, etc. +- `db-name`: Database name +- `engine`: Database storage engine, InnoDB is recommended +- `log-mode`: Database log mode, options are `silent`, `error`, `warn`, `info` +- `log-zap`: Whether to use zap log library to record database logs +- `max-idle-conns`: Maximum number of idle connections +- `max-lifetime`: Maximum connection lifetime, in seconds +- `max-open-conns`: Maximum number of open connections +- `password`: Database password +- `path`: Database server address +- `port`: Database server port +- `prefix`: Database table name prefix +- `singular`: Whether to use singular table names (default is plural) +- `username`: Database username + +### quota Quota Limit Configuration + +```yaml +quota: + default-level: 1 + instance-type-permissions: + min-level-for-container: 1 + min-level-for-delete: 2 + min-level-for-vm: 1 + level-limits: + 1: + max-instances: 1 + max-resources: + bandwidth: 10 + cpu: 1 + disk: 1025 + memory: 350 + max-traffic: 102400 + 2: + max-instances: 3 + max-resources: + bandwidth: 20 + cpu: 2 + disk: 20480 + memory: 1024 + max-traffic: 204800 + 3: + max-instances: 5 + max-resources: + bandwidth: 50 + cpu: 4 + disk: 40960 + memory: 2048 + max-traffic: 307200 + 4: + max-instances: 10 + max-resources: + bandwidth: 100 + cpu: 8 + disk: 81920 + memory: 4096 + max-traffic: 409600 + 5: + max-instances: 20 + max-resources: + bandwidth: 200 + cpu: 16 + disk: 163840 + memory: 8192 + max-traffic: 512000 +``` + +Configuration for controlling user levels and resource quotas. The default unit for memory, disk, and traffic is MB. + +#### Global Configuration + +- `default-level`: Default level for newly registered users + +#### instance-type-permissions Instance Type Permissions + +Controls the types of operations that users of different levels can perform. + +- `min-level-for-container`: Minimum user level required to create container instances +- `min-level-for-delete`: Minimum level required to perform delete operations on the regular user side +- `min-level-for-vm`: Minimum user level required to create virtual machine instances + +#### level-limits Level Quota Limits + +Defines the resource quota limits corresponding to each user level, with the key being the level number. + +Each level includes the following configurations: + +- `max-instances`: Maximum number of instances that users of this level can create +- `max-resources`: Maximum resource limits for a single instance + - `bandwidth`: Maximum bandwidth, in Mbps + - `cpu`: Maximum number of CPU cores + - `disk`: Maximum disk space, in MB + - `memory`: Maximum memory, in MB +- `max-traffic`: Maximum total traffic for users of this level, in MB + +### zap Log Configuration + +```yaml +zap: + compress-logs: true + director: storage/logs + encode-level: LowercaseLevelEncoder + format: console + level: info + log-in-console: false + max-array-elements: 5 + max-backups: 15 + max-file-size: 5 + max-log-length: 2000 + max-string-length: 1000 + prefix: '[oneclickvirt]' + retention-day: 3 + show-line: false + stacktrace-key: stacktrace +``` + +Detailed configuration for system log recording, based on the zap log library. + +- `compress-logs`: Whether to compress archived log files +- `director`: Log file storage directory +- `encode-level`: Log level encoding method, options are `LowercaseLevelEncoder` (lowercase), `CapitalLevelEncoder` (uppercase) +- `format`: Log output format, options are `console` (console format), `json` (JSON format) +- `level`: Log level, options are `debug`, `info`, `warn`, `error`. It is recommended to use `debug` during development and debugging, and `info` or `warn` in production environments +- `log-in-console`: Whether to also output logs to the console +- `max-array-elements`: Maximum number of elements recorded for array type fields +- `max-backups`: Maximum number of historical log files to retain +- `max-file-size`: Maximum size of a single log file, in MB +- `max-log-length`: Maximum length of a single log entry; parts exceeding this will be truncated +- `max-string-length`: Maximum recording length for string fields +- `prefix`: Log prefix identifier +- `retention-day`: Number of days to retain log files; expired files are automatically deleted +- `show-line`: Whether to display the filename and line number of the log call +- `stacktrace-key`: Key name for stack trace information + +Note: When debugging issues, `level` should be set to `debug` to obtain detailed log information. \ No newline at end of file diff --git a/docs/en/guide/oneclickvirt/oneclickvirt_install.md b/docs/en/guide/oneclickvirt/oneclickvirt_install.md index 8c397b42ab..b347f4b801 100644 --- a/docs/en/guide/oneclickvirt/oneclickvirt_install.md +++ b/docs/en/guide/oneclickvirt/oneclickvirt_install.md @@ -4,34 +4,35 @@ outline: deep # OneClickVirt -Distinguishes between panel side and controlled side. The controlled side needs to have the corresponding virtualization environment installed in advance, which can be installed using the main installation instructions in this documentation. +Distinguish between the control panel and the controlled end. The controlled end needs to have the corresponding virtualization environment installed in advance. You can use the installation instructions from other sections of this document for environment installation. The control panel is actually just a panel without virtualization environment requirements. -## Controlled Side +## Controlled End -Corresponds to the main installation instructions in this documentation for environment installation. This will not be elaborated here. This tutorial has corresponding installation commands for the four major mainstream virtualization technologies. Please refer to them yourself. +Refer to the installation instructions from other sections of this document for environment installation. This won't be elaborated further here. This tutorial provides corresponding installation commands for the four mainstream virtualization technologies. Please refer to them on your own. -If you need to use the panel's traffic control, you need to install the ```vnstat``` tool, download it yourself, like +If you need to use the panel's traffic control feature, you'll need to additionally install the ```vnstat``` tool. Download it yourself. If using apt package management, you can use: -```shell -apt install -y vnstat +```shell +apt install -y vnstat ``` -## Panel Side +to download it. The same applies to other systems. -The host machine needs to have one of ```nginx``` or ```caddy``` or ```OpenResty``` installed, as well as ```mysql``` version ```8.4.6```, requiring at least 1G of free memory and 2G of free disk space. +## Control Panel -After installation is complete, the default startup addresses are: +Hardware requirements: at least 1GB of free memory and 2GB of free disk space. Installation can be completed through any of the following methods. -Frontend: ```http://your-IP-or-domain``` - -Backend API: ```http://localhost:8888``` - -API Documentation: ```http://localhost:8888/swagger/index.html``` +| Installation Method | Use Case | Advantages | Disadvantages | +|---------|---------|------|------| +| Docker Deployment (Pre-built Image) | Quick deployment, larger footprint | One-click installation, data persistence | Requires Docker environment, large image download | +| Frontend-Backend Separation Deployment | High performance, minimal footprint | Best performance, flexible configuration | Complex configuration, requires reverse proxy setup | +| All-in-One Deployment | Works with or without public IPv4 address | Simple deployment, no reverse proxy needed | Lower performance | +| Dockerfile Self-compilation | Suitable for secondary development and source code release | Highly customizable | Requires Docker environment, long compilation time | ### Installation via Docker :::tip -Since the database starts together when starting, do not operate immediately when the container just starts. You need to wait at least 12 seconds. +Since the database starts together with the container, do not operate immediately after container startup. Wait at least 12 seconds. ::: Available image tags can be found at: @@ -40,22 +41,22 @@ https://hub.docker.com/r/spiritlhl/oneclickvirt https://github.com/oneclickvirt/oneclickvirt/pkgs/container/oneclickvirt -#### Method 1: Using Pre-built Images +#### Method 1: Deploy Using Pre-built Images **Image Tag Description** | Image Tag | Description | Use Case | |---------|------|---------| -| `spiritlhl/oneclickvirt:latest` | Integrated version (built-in database) latest | Quick deployment | -| `spiritlhl/oneclickvirt:20251015` | Integrated version specific date version | Need fixed version | -| `spiritlhl/oneclickvirt:no-db` | Independent database version latest | Without built-in database | -| `spiritlhl/oneclickvirt:no-db-20251015` | Independent database version specific date | Without built-in database | +| `spiritlhl/oneclickvirt:latest` | All-in-one version (with built-in database) latest | Quick deployment | +| `spiritlhl/oneclickvirt:20251015` | All-in-one version specific date | Need fixed version | +| `spiritlhl/oneclickvirt:no-db` | Independent database version latest | No built-in database | +| `spiritlhl/oneclickvirt:no-db-20251015` | Independent database version specific date | No built-in database | -All images support `linux/amd64` and `linux/arm64` architectures. +All images support both `linux/amd64` and `linux/arm64` architectures. -**Deployment in Fresh Environment** +**Deploy in Fresh Environment** -Using pre-built `amd64` or `arm64` images, will automatically download the corresponding version based on current system architecture: +Using pre-built ```amd64``` or ```arm64``` images, the corresponding version will be automatically downloaded based on the current system architecture: Without domain configuration: @@ -84,58 +85,58 @@ docker run -d \ spiritlhl/oneclickvirt:latest ``` -The above methods are only for fresh installation +The above methods are only for new installations. **Upgrade Frontend and Backend Only in Existing Environment** -No need to delete mounted volumes, just delete the container itself +Delete only the container itself without removing mounted volumes: ```shell docker rm -f oneclickvirt ``` -Then delete the original image +Then delete the original image: ```shell docker image rm -f spiritlhl/oneclickvirt:latest ``` -Pull the container image again +Pull the container image again: ```shell docker pull spiritlhl/oneclickvirt:latest ``` -Then follow the steps for deployment in fresh environment, note that after waiting 12 seconds to open the frontend, you will find it automatically skips the initialization interface because the data has been saved and is available +Then follow the steps for fresh environment deployment. Note that after waiting 12 seconds and opening the frontend, you'll find it automatically skips the initialization interface because the data has been persisted and imported. **Redeploy in Existing Environment** -Need to delete not only the container but also the corresponding mounts: +This will completely delete existing data before deployment. You need to delete not only the container but also the corresponding mount points: ```shell docker rm -f oneclickvirt docker volume rm oneclickvirt-data oneclickvirt-storage ``` -Then delete the original image +Then delete the original image: ```shell docker image rm -f spiritlhl/oneclickvirt:latest ``` -Pull the container image again +Pull the container image again: ```shell docker pull spiritlhl/oneclickvirt:latest ``` -Then follow the steps for deployment in fresh environment, this will prompt for reinitialization, all original data has been deleted. +Then follow the steps for fresh environment deployment. This will prompt for re-initialization, and all original data has been deleted. -#### Method 2: Build and Package Yourself +#### Method 2: Self-compile and Deploy via Dockerfile -If you need to modify source code or custom build: +This method is suitable for modifying source code and custom builds: -**Integrated version (built-in database)** +**All-in-One Version (with built-in database)** ```bash git clone https://github.com/oneclickvirt/oneclickvirt.git @@ -150,7 +151,7 @@ docker run -d \ oneclickvirt ``` -**Independent database version:** +**Independent Database Version (no built-in database)** ```bash git clone https://github.com/oneclickvirt/oneclickvirt.git @@ -172,29 +173,35 @@ docker run -d \ ### Installation via Pre-compiled Binary Files -#### Linux +There are also two methods here: +- Frontend-backend separation deployment (backend and frontend are compiled separately into corresponding files for deployment), better performance +- All-in-one deployment (frontend and backend are integrated into one file for deployment), lower performance + +#### Frontend-Backend Separation Deployment + +##### Linux Download and execute -International +International: ```shell curl -L https://raw.githubusercontent.com/oneclickvirt/oneclickvirt/refs/heads/main/install.sh -o install.sh && chmod +x install.sh ``` -Domestic (China) +Domestic: ```shell curl -L https://cdn.spiritlhl.net/https://raw.githubusercontent.com/oneclickvirt/oneclickvirt/refs/heads/main/install.sh -o install.sh && chmod +x install.sh ``` -Install environment with interaction +Interactive environment installation: ``` ./install.sh ``` -Install environment without interaction +Non-interactive environment installation: ``` noninteractive=true ./install.sh @@ -236,13 +243,11 @@ journalctl -u oneclickvirt -f Restart service: -Stop service: - ```shell systemctl restart oneclickvirt ``` -The previous installation script will extract the static files to +The installation script will extract static files to: ```shell cd /opt/oneclickvirt/web/ @@ -250,15 +255,15 @@ cd /opt/oneclickvirt/web/ this path. -Use ```nginx``` or ```caddy``` to establish a static website with this path. Whether you need domain binding is your choice. +Use ```nginx``` or ```caddy``` to establish a static website with this path. Whether to bind a domain name is your choice. -After the static files are deployed, you need to reverse proxy the backend address for frontend use. Here is a specific example using ```OpenResty```: +After deploying the static files, you need to reverse proxy the backend address for frontend use. Here's a specific example using ```OpenResty```: ![](./images/proxy.png) -You need to reverse proxy the path ```/api``` to the backend address ```http://127.0.0.1:8888```. If you are using ```1panel```, you only need to fill in these settings. The default backend domain uses the default ```$host``` and does not need to be modified. +You need to reverse proxy the path ```/api``` to the backend address ```http://127.0.0.1:8888```. If you're using ```1panel```, you only need to fill in these fields, and the default backend domain uses the default ```$host``` without modification. -If you are using ```nginx``` or ```caddy```, please refer to the proxy source code below and modify it yourself for proxying: +If you're using ```nginx``` or ```caddy```, please refer to the proxy source code below and modify it for your own proxy setup: ```shell location /api { @@ -279,208 +284,104 @@ location /api { } ``` -#### Windows +##### Windows -Check +Check: https://github.com/oneclickvirt/oneclickvirt/releases/latest -Download the latest compressed file for the corresponding architecture, extract and execute in the background. +Download the latest compressed file for the corresponding architecture, extract and execute. -In the same directory as the executed binary file, download +In the same directory as the executing binary file, download: https://cdn.spiritlhl.net/https://raw.githubusercontent.com/oneclickvirt/oneclickvirt/refs/heads/main/server/config.yaml -This is the configuration file that will be needed subsequently. +This is the configuration file needed for subsequent use. -After downloading the ```web-dist.zip``` file, extract it and use the corresponding program to establish a static website, and set up the reverse proxy similar to Linux. +After downloading the ```web-dist.zip``` file, extract it and use the corresponding program to establish a static website, setting up the reverse proxy similar to Linux. -#### Database Initialization +#### All-in-One Deployment -After installing and starting ```mysql```, create an empty database ```oneclickvirt``` with type ```utf8mb4```. It's best to make it accessible only locally ```127.0.0.1```. Save the corresponding username and password. +Here we no longer distinguish between frontend and backend concepts. From: + +https://github.com/oneclickvirt/oneclickvirt/releases/latest + +Find the compressed package with the ```allinone``` tag to download. Note the distinction between ```amd64``` and ```arm64``` architectures, as well as the corresponding systems. + +In Linux, use the ```tar -zxvf``` command to extract the ```tar.gz``` compressed package. In Windows, use the corresponding extraction tool to extract the ```zip``` compressed package, and copy the binary file to the location where you need to deploy the project. + +It's best to move it to a dedicated folder, as structured log files will be generated during operation. + +(The following instructions will use the amd64 architecture Linux system file as an example) + +In Linux, grant executable permissions to the file, such as: + +```shell +chmod 777 server-allinone-linux-amd64 +``` + +Then download: + +https://github.com/oneclickvirt/oneclickvirt/blob/main/server/config.yaml + +to the same folder. + +In Linux, use ```screen``` or ```tmux``` or ```nohup``` commands to execute the binary file in the background, such as: + +```shell +./server-allinone-linux-amd64 +``` + +Then open port 8888 of the corresponding IP address to see the frontend for use, such as: + +``` +http://your-IP-address:8888 +``` + +If you're on a Windows system, you need to start the exe file with administrator privileges, and ensure that the ```config.yaml``` configuration file exists in the same folder as the exe file before starting, otherwise startup will result in a white screen or connection issues. As for how to execute it in the background, explore on your own. You can also directly run it with the cmd window open. + +The all-in-one deployment mode is suitable for situations where the local machine doesn't have a public IP. Your IP address can be ```localhost``` or ```127.0.0.1```, or it can be the corresponding public IPv4 address. Test in your specific deployment environment. + +## Database Initialization + +After installing and starting ```mysql```, create an empty database ```oneclickvirt```, using type ```utf8mb4```, preferably accessible only locally via ```127.0.0.1```. Save the corresponding username and password. (If you're using the all-in-one Docker deployment container, the database is included and you don't need to create an empty database yourself. By default, the corresponding database has already been started in the container and is available.) After opening the corresponding frontend page, it will automatically redirect to the initialization interface. ![](./images/init.png) -Fill in the database information and related user information. If the database connection test is successful, you can click to initialize the system. +Fill in the database information and related user information. Test the database connection, and if there are no issues, you can click to initialize the system. ![](./images/init_success.png) -After completing initialization, it will automatically redirect to the homepage, and you can explore and use it yourself. +After completing initialization, it will automatically redirect to the homepage, where you can explore and use it on your own. ![](./images/home.png) -If you use the default user information for initialization, the default accounts are: +If you used the default user information for initialization, the default account is: -Administrator account name +Administrator account username and password are: ``` admin ``` -Administrator password - ``` Admin123!@# ``` -Regular user account name +Regular user account username and password are: ``` testuser ``` -Regular user password - ``` TestUser123!@# ``` -All images are loaded by default, but only images related to ```debian``` and ```alpine``` are enabled by default, so as to avoid too many images being enabled and making it difficult for users to choose. If you need additional types of images, you need to search and enable them by type of architecture version in the image management interface under administrator privileges. +During initialization, all image seed data is loaded into the database by default, but by default only ```debian``` and ```alpine``` related version images are enabled. This is to avoid user choice paralysis caused by too many enabled images. -## Configuration File (Optional) +If you need additional types of images, you need to search and enable them by type, architecture, and version in the system image management interface under administrator privileges. -The default settings are sufficient for light usage. If you need advanced customization, you need to modify the configuration file or make changes in the admin interface after initialization. - -https://github.com/oneclickvirt/oneclickvirt/blob/main/server/config.yaml - -Here is the complete initialization configuration file. The specific configuration items will be explained below. - -```shell -auth: - email-password: "" - email-smtp-host: "" - email-smtp-port: "3306" - email-username: root - enable-email: false - enable-oauth2: false - enable-public-registration: false - enable-qq: false - enable-telegram: false - qq-app-id: "" - qq-app-key: "" - telegram-bot-token: "" - frontend-url: "" -``` - -If you need to use the OAuth2 functionality, you must enter the ```frontend-url``` here as the final address displayed in your frontend. Include the ```http``` or ```https``` protocol prefix, and the trailing slash (```/```) is optional. - -Other default system configuration items. The configuration will be read from here during initialization, and will be automatically written back when updating system configuration. - -```shell -captcha: - enabled: true - expire-time: 300 - height: 40 - length: 4 - width: 120 -``` - -Configuration items for the image captcha on the frontend login and registration pages. - -```shell -cdn: - base-endpoint: https://cdn.spiritlhl.net/ - endpoints: - - https://cdn0.spiritlhl.top/ - - http://cdn3.spiritlhl.net/ - - http://cdn1.spiritlhl.net/ - - http://cdn2.spiritlhl.net/ -``` - -Acceleration addresses to try when downloading images. Generally, no modification is needed, as the preloaded system images are all from repositories under this organization, and these CDNs are sufficient for accelerated downloads. - -```shell -mysql: - auto-create: true - config: charset=utf8mb4&parseTime=True&loc=Local - db-name: oneclickvirt - engine: InnoDB - log-mode: error - log-zap: false - max-idle-conns: 10 - max-lifetime: 3600 - max-open-conns: 100 - password: "" - path: - port: - prefix: "" - singular: false - username: root -``` - -During initialization, if both ```path``` and ```port``` in this section are empty, initialization is required. In this case, the database you enter for initialization must be an empty database. - -```shell -quota: - default-level: 1 - instance-type-permissions: - min-level-for-container: 1 - min-level-for-delete: 2 - min-level-for-vm: 1 - level-limits: - 1: - max-instances: 1 - max-resources: - bandwidth: 10 - cpu: 1 - disk: 1025 - memory: 350 - max-traffic: 102400 - 2: - max-instances: 3 - max-resources: - bandwidth: 20 - cpu: 2 - disk: 20480 - memory: 1024 - max-traffic: 204800 - 3: - max-instances: 5 - max-resources: - bandwidth: 50 - cpu: 4 - disk: 40960 - memory: 2048 - max-traffic: 307200 - 4: - max-instances: 10 - max-resources: - bandwidth: 100 - cpu: 8 - disk: 81920 - memory: 4096 - max-traffic: 409600 - 5: - max-instances: 20 - max-resources: - bandwidth: 200 - cpu: 16 - disk: 163840 - memory: 8192 - max-traffic: 512000 -``` - -This section contains configuration items for level and quota restrictions. The default unit for memory, disk, and traffic is ```mb```. The ```min-level``` configuration sets the minimum permissions in the system configuration. By default, level 1 can create containers, level 2 can perform delete operations on the regular user side, and level 1 can create virtual machines by default. ```default-level``` is the default level for newly registered users. - -```shell -zap: - compress-logs: true - director: storage/logs - encode-level: LowercaseLevelEncoder - format: console - level: info - log-in-console: false - max-array-elements: 5 - max-backups: 15 - max-file-size: 5 - max-log-length: 2000 - max-string-length: 1000 - prefix: '[oneclickvirt]' - retention-day: 3 - show-line: false - stacktrace-key: stacktrace -``` - -The only field that needs attention in this section is ```level```, which defaults to ```info``` logging. If you need debug logs, please change it to ```debug```. +Please immediately change the default administrator username and password after initialization, and disable or delete the default enabled test user. This can be done in the administrator's user management page. \ No newline at end of file diff --git a/docs/guide/oneclickvirt/oneclickvirt_custom.md b/docs/guide/oneclickvirt/oneclickvirt_custom.md index 0c1dbced12..2c49e7269a 100644 --- a/docs/guide/oneclickvirt/oneclickvirt_custom.md +++ b/docs/guide/oneclickvirt/oneclickvirt_custom.md @@ -2,5 +2,243 @@ outline: deep --- +## 配置文件 -占位待施工 \ No newline at end of file +默认的设置已经足够轻度使用了,如果需要高级自定义则需要修改配置文件,或初始化后在管理员界面进行修改。 + +https://github.com/oneclickvirt/oneclickvirt/blob/main/server/config.yaml + +这里是完整的初始化的配置文件,下面将讲解具体的配置项目: + +### auth 认证配置 + +```yaml +auth: + email-password: "" + email-smtp-host: "" + email-smtp-port: "3306" + email-username: root + enable-email: false + enable-oauth2: false + enable-public-registration: false + enable-qq: false + enable-telegram: false + qq-app-id: "" + qq-app-key: "" + telegram-bot-token: "" + frontend-url: "" +``` + +认证模块的配置项,用于控制用户登录注册的方式和第三方登录集成。 + +- `email-password`: 邮件服务的认证密码,用于SMTP发送邮件时的身份验证 +- `email-smtp-host`: SMTP服务器地址,如 `smtp.gmail.com` +- `email-smtp-port`: SMTP服务器端口,常用端口为 `25`、`465`(SSL)、`587`(TLS) +- `email-username`: SMTP服务器登录用户名,通常是完整的邮箱地址 +- `enable-email`: 是否启用邮箱登录功能 +- `enable-oauth2`: 是否启用OAuth2第三方登录功能 +- `enable-public-registration`: 是否允许公开注册,关闭后仅管理员可创建账号 +- `enable-qq`: 是否启用QQ登录 +- `enable-telegram`: 是否启用Telegram登录 +- `qq-app-id`: QQ互联平台申请的App ID +- `qq-app-key`: QQ互联平台申请的App Key +- `telegram-bot-token`: Telegram Bot的API Token +- `frontend-url`: 前端访问地址,需要包含协议头(`http://`或`https://`),结尾斜杠可选。OAuth2回调地址依赖此配置 + +### captcha 验证码配置 + +```yaml +captcha: + enabled: true + expire-time: 300 + height: 40 + length: 4 + width: 120 +``` + +图形验证码的生成和验证配置,用于前端登录注册页面的安全验证。 + +- `enabled`: 是否启用验证码功能 +- `expire-time`: 验证码过期时间,单位为秒 +- `height`: 验证码图片高度,单位为像素 +- `length`: 验证码字符长度 +- `width`: 验证码图片宽度,单位为像素 + +### cdn 内容分发网络配置 + +```yaml +cdn: + base-endpoint: https://cdn.spiritlhl.net/ + endpoints: + - https://cdn0.spiritlhl.top/ + - http://cdn3.spiritlhl.net/ + - http://cdn1.spiritlhl.net/ + - http://cdn2.spiritlhl.net/ +``` + +系统镜像下载时使用的CDN加速节点配置。 + +- `base-endpoint`: 主CDN节点地址,优先使用 +- `endpoints`: 备用CDN节点列表,按顺序进行重试。系统会自动选择可用节点进行镜像下载 + +一般情况下不需要修改此配置,预载的系统镜像都托管在本组织仓库中,默认CDN节点已能提供良好的下载加速。 + +### mysql 数据库配置 + +```yaml +mysql: + auto-create: true + config: charset=utf8mb4&parseTime=True&loc=Local + db-name: oneclickvirt + engine: InnoDB + log-mode: error + log-zap: false + max-idle-conns: 10 + max-lifetime: 3600 + max-open-conns: 100 + password: "" + path: "" + port: "" + prefix: "" + singular: false + username: root +``` + +MySQL数据库连接和行为配置。初始化判断逻辑:当`path`和`port`都为空时,系统认为需要进行初始化,此时必须确保目标数据库为空数据库。 + +- `auto-create`: 是否自动创建数据库(如果不存在) +- `config`: 数据库连接参数,包括字符集、时间解析等 +- `db-name`: 数据库名称 +- `engine`: 数据库存储引擎,推荐使用InnoDB +- `log-mode`: 数据库日志模式,可选值为`silent`、`error`、`warn`、`info` +- `log-zap`: 是否使用zap日志库记录数据库日志 +- `max-idle-conns`: 最大空闲连接数 +- `max-lifetime`: 连接最大生命周期,单位为秒 +- `max-open-conns`: 最大打开连接数 +- `password`: 数据库密码 +- `path`: 数据库服务器地址 +- `port`: 数据库服务器端口 +- `prefix`: 数据表名前缀 +- `singular`: 是否使用单数表名(默认为复数) +- `username`: 数据库用户名 + +### quota 配额限制配置 + +```yaml +quota: + default-level: 1 + instance-type-permissions: + min-level-for-container: 1 + min-level-for-delete: 2 + min-level-for-vm: 1 + level-limits: + 1: + max-instances: 1 + max-resources: + bandwidth: 10 + cpu: 1 + disk: 1025 + memory: 350 + max-traffic: 102400 + 2: + max-instances: 3 + max-resources: + bandwidth: 20 + cpu: 2 + disk: 20480 + memory: 1024 + max-traffic: 204800 + 3: + max-instances: 5 + max-resources: + bandwidth: 50 + cpu: 4 + disk: 40960 + memory: 2048 + max-traffic: 307200 + 4: + max-instances: 10 + max-resources: + bandwidth: 100 + cpu: 8 + disk: 81920 + memory: 4096 + max-traffic: 409600 + 5: + max-instances: 20 + max-resources: + bandwidth: 200 + cpu: 16 + disk: 163840 + memory: 8192 + max-traffic: 512000 +``` + +用户等级和资源配额的控制配置。内存、硬盘、流量的默认单位均为MB。 + +#### 全局配置 + +- `default-level`: 新注册用户的默认等级 + +#### instance-type-permissions 实例类型权限 + +控制不同等级用户可以执行的操作类型。 + +- `min-level-for-container`: 创建容器实例所需的最低用户等级 +- `min-level-for-delete`: 在普通用户端执行删除操作所需的最低等级 +- `min-level-for-vm`: 创建虚拟机实例所需的最低用户等级 + +#### level-limits 等级配额限制 + +定义每个用户等级对应的资源配额上限,键为等级数字。 + +每个等级包含以下配置: + +- `max-instances`: 该等级用户可创建的最大实例数量 +- `max-resources`: 单个实例的最大资源限制 + - `bandwidth`: 最大带宽,单位为Mbps + - `cpu`: 最大CPU核心数 + - `disk`: 最大硬盘空间,单位为MB + - `memory`: 最大内存,单位为MB +- `max-traffic`: 该等级用户的最大总流量,单位为MB + +### zap 日志配置 + +```yaml +zap: + compress-logs: true + director: storage/logs + encode-level: LowercaseLevelEncoder + format: console + level: info + log-in-console: false + max-array-elements: 5 + max-backups: 15 + max-file-size: 5 + max-log-length: 2000 + max-string-length: 1000 + prefix: '[oneclickvirt]' + retention-day: 3 + show-line: false + stacktrace-key: stacktrace +``` + +系统日志记录的详细配置,基于zap日志库。 + +- `compress-logs`: 是否压缩归档的日志文件 +- `director`: 日志文件存储目录 +- `encode-level`: 日志级别编码方式,可选`LowercaseLevelEncoder`(小写)、`CapitalLevelEncoder`(大写) +- `format`: 日志输出格式,可选`console`(控制台格式)、`json`(JSON格式) +- `level`: 日志级别,可选`debug`、`info`、`warn`、`error`。开发调试时建议使用`debug`,生产环境使用`info`或`warn` +- `log-in-console`: 是否同时输出日志到控制台 +- `max-array-elements`: 数组类型字段最大记录元素数 +- `max-backups`: 保留的历史日志文件最大数量 +- `max-file-size`: 单个日志文件最大大小,单位为MB +- `max-log-length`: 单条日志最大长度,超出部分会被截断 +- `max-string-length`: 字符串字段最大记录长度 +- `prefix`: 日志前缀标识 +- `retention-day`: 日志文件保留天数,过期自动删除 +- `show-line`: 是否显示日志调用的文件名和行号 +- `stacktrace-key`: 堆栈跟踪信息的键名 + +注意:调试问题时应将`level`设置为`debug`以获取详细日志信息。 \ No newline at end of file diff --git a/docs/guide/oneclickvirt/oneclickvirt_install.md b/docs/guide/oneclickvirt/oneclickvirt_install.md index 594eb9b55c..5238197397 100644 --- a/docs/guide/oneclickvirt/oneclickvirt_install.md +++ b/docs/guide/oneclickvirt/oneclickvirt_install.md @@ -4,7 +4,7 @@ outline: deep # OneClickVirt -区分面板端和受控端,受控端需要提前安装好对应虚拟化的环境,可使用本说明别的主体安装进行环境安装 +区分面板端和受控端,受控端需要提前安装好对应虚拟化的环境,可使用本说明别的主体安装进行环境安装,主控端实际就是一个面板,没有虚拟化环境需求。 ## 受控端 @@ -20,15 +20,14 @@ apt install -y vnstat ## 面板端 -宿主机需要安装好```nginx```或```caddy```或```OpenResty```之一,以及```8.4.6```版本的```mysql```,需要至少1G空闲内存和2G空闲硬盘。 +硬件上需要至少1G空闲内存和2G空闲硬盘,通过下面任一方式安装完成即可。 -安装完成后,默认启动的地址 - -前端:```http://你的IP或者域名``` - -后端 API:```http://localhost:8888``` - -API 文档:```http://localhost:8888/swagger/index.html``` +| 安装方式 | 适用场景 | 优点 | 缺点 | +|---------|---------|------|------| +| Docker部署(预构建镜像) | 快速部署,占用较大 | 一键安装、数据持久化 | 需要Docker环境,下载镜像较大 | +| 前后端分离部署 | 高性能,占用最小 | 性能最佳、灵活配置 | 配置复杂,需配置反向代理 | +| 一体化部署 | 本地有无公网IPV4地址皆可 | 部署简单、无需反向代理 | 性能较差 | +| Dockerfile自编译 | 适合二次开发源码发布 | 高度自定义 | 需要Docker环境,编译耗时长 | ### 通过Docker安装 @@ -44,7 +43,7 @@ https://github.com/oneclickvirt/oneclickvirt/pkgs/container/oneclickvirt 中查询 -#### 方式一:使用预构建镜像 +#### 方式一:使用预构建镜像部署 **镜像标签说明** @@ -57,7 +56,7 @@ https://github.com/oneclickvirt/oneclickvirt/pkgs/container/oneclickvirt 所有镜像均支持 `linux/amd64` 和 `linux/arm64` 架构。 -**全新环境下开设** +**全新环境下部署** 使用已构建好的```amd64```或```arm64```镜像,会自动根据当前系统架构下载对应版本: @@ -92,42 +91,42 @@ docker run -d \ **旧有环境下仅升级前后端** -不需要删除挂载盘仅删除容器本身即可 +不需要删除挂载盘仅删除容器本身: ```shell docker rm -f oneclickvirt ``` -然后删除原始的镜像 +然后删除原始的镜像: ```shell docker image rm -f spiritlhl/oneclickvirt:latest ``` -重新拉取容器镜像 +重新拉取容器镜像: ```shell docker pull spiritlhl/oneclickvirt:latest ``` -然后再按全新环境下开设的步骤来,注意等待12秒后打开前端,会发现已自动越过初始化界面,因为数据已保存可用 +然后再按全新环境下开设的步骤来,注意等待12秒后打开前端,会发现已自动越过初始化界面,因为数据已持久化导入。 -**旧有环境下重新开设** +**旧有环境下重新部署** -不仅需要删除容器还得删除对应的挂载: +这将完全删除原有数据再部署,不仅需要删除容器还得删除对应的挂载点: ```shell docker rm -f oneclickvirt docker volume rm oneclickvirt-data oneclickvirt-storage ``` -然后删除原始的镜像 +然后删除原始的镜像: ```shell docker image rm -f spiritlhl/oneclickvirt:latest ``` -重新拉取容器镜像 +重新拉取容器镜像: ```shell docker pull spiritlhl/oneclickvirt:latest @@ -135,9 +134,9 @@ docker pull spiritlhl/oneclickvirt:latest 然后再按全新环境下开设的步骤来,这样会提示重新初始化,所有原始数据已删除。 -#### 方式二:自己编译打包 +#### 方式二:通过Dockerfile自行编译部署 -如果需要修改源码或自定义构建: +这种方式适合自行修改源码与自定义构建: **一体化版本(内置数据库)** @@ -154,7 +153,7 @@ docker run -d \ oneclickvirt ``` -**独立数据库版本:** +**独立数据库版本(不内置数据库)** ```bash git clone https://github.com/oneclickvirt/oneclickvirt.git @@ -176,7 +175,13 @@ docker run -d \ ### 通过预编译二进制文件安装 -#### Linux +这里也区分两种方式: +- 前后端分离部署(后端前端分开编译出对应文件进行部署),性能更好 +- 一体化部署(前后端和二为一只需要部署一个文件),性能较差 + +#### 前后端分离部署 + +##### Linux 下载并执行 @@ -283,7 +288,7 @@ location /api { } ``` -#### Windows +##### Windows 查看 @@ -299,9 +304,51 @@ https://cdn.spiritlhl.net/https://raw.githubusercontent.com/oneclickvirt/oneclic 下载```web-dist.zip```文件后,解压并使用对应的程序建立静态网站,类似Linux那样设置好反向代理即可。 -#### 数据库初始化 +#### 一体化部署 -安装启动了```mysql```后,创建一个空的数据库```oneclickvirt```,使用类型```utf8mb4```,最好仅本地```127.0.0.1```可访问,对应用户名和密码保存好。 +这里不再区分前后端的概念,从 + +https://github.com/oneclickvirt/oneclickvirt/releases/latest + +中找到带```allinone```标签的压缩包进行下载,注意区分```amd64```和```arm64```架构,以及对应的系统。 + +Linux中使用```tar -zxvf```命令解压```tar.gz```压缩包,Windows中使用对应解压工具解压```zip```压缩包,将其中的二进制文件复制粘贴到你需要部署项目的位置。 + +最好移动到一个专门的文件夹中,因为运行过程中将产生结构化的日志文件。 + +(以下说明将以amd64架构的linux系统的文件进行示例) + +Linux中赋予文件可执行权限,如 + +```shell +chmod 777 server-allinone-linux-amd64 +``` + +然后下载 + +https://github.com/oneclickvirt/oneclickvirt/blob/main/server/config.yaml + +文件到同一个文件夹中。 + +Linux中,使用```screen```或```tmux```或```nohup```命令挂起执行二进制文件即可,如 + +```shell +./server-allinone-linux-amd64 +``` + +然后打开对应的IP地址的8888端口即可看到前端进行使用了,如 + +``` +http://你的IP地址:8888 +``` + +如果你是Windows系统,那么需要使用管理员权限启动exe文件,同时确保启动前exe文件同一个文件夹中存在```config.yaml```配置文件,否则启动将出现白屏或不通的情况。至于怎么挂起执行,自行探索吧,直接挂着cmd界面运行也行。 + +一体化部署的模式适合本机没有公网IP的情况,你的IP地址可以是```localhost```或者```127.0.0.1```,也可以是对应的公网IPV4地址,具体部署环境下自测。 + +## 数据库初始化 + +安装启动了```mysql```后,创建一个空的数据库```oneclickvirt```,使用类型```utf8mb4```,最好仅本地```127.0.0.1```可访问,对应用户名和密码保存好。(如果你安装使用的是docker一体化部署的容器,自带数据库无需自己创建空数据库,默认已在容器中启动了对应的数据库可用了) 打开前端对应的页面后,将自动跳转到初始化界面。 @@ -317,175 +364,28 @@ https://cdn.spiritlhl.net/https://raw.githubusercontent.com/oneclickvirt/oneclic 如果使用的是默认的用户信息进行初始化,那么默认的账户为: -管理员账户名 +管理员账户名密码分别为: ``` admin ``` -管理员密码 - ``` Admin123!@# ``` -普通用户账户名 +普通用户账户名密码分别为: ``` testuser ``` -普通用户密码 - ``` TestUser123!@# ``` -默认加载了所有的镜像,但是默认仅启用了```debian```和```alpine```相关版本的镜像,避免过多镜像启用导致用户选择困难。如果你需要额外类型的镜像,则需要在管理员权限下,在镜像管理界面按照类型架构版本搜索并进行启用。 +初始化过程中,默认加载了所有的镜像种子数据到数据库中,但是默认仅启用了```debian```和```alpine```相关版本的镜像,这是为了避免过多镜像启用导致用户选择困难。 -## 配置文件(可选) - -默认的设置已经足够轻度使用了,如果需要高级自定义则需要修改配置文件,或初始化后在管理员界面进行修改。 - -https://github.com/oneclickvirt/oneclickvirt/blob/main/server/config.yaml - -这里是完整的初始化的配置文件,下面将讲解具体的配置项目 - -```shell -auth: - email-password: "" - email-smtp-host: "" - email-smtp-port: "3306" - email-username: root - enable-email: false - enable-oauth2: false - enable-public-registration: false - enable-qq: false - enable-telegram: false - qq-app-id: "" - qq-app-key: "" - telegram-bot-token: "" - frontend-url: "" -``` - -如果需要使用oauth2功能,那么需要填写这里的```frontend-url```地址为你最终前端展示的地址,带```http```或```https```协议头,尾部带不带```/```都行 - -其他的默认的系统配置项,初始化的时候会从这里读取配置,更新系统配置时会自动回写 - -```shell -captcha: - enabled: true - expire-time: 300 - height: 40 - length: 4 - width: 120 -``` - -前端登录注册时的图片验证码的配置项 - -```shell -cdn: - base-endpoint: https://cdn.spiritlhl.net/ - endpoints: - - https://cdn0.spiritlhl.top/ - - http://cdn3.spiritlhl.net/ - - http://cdn1.spiritlhl.net/ - - http://cdn2.spiritlhl.net/ -``` - -镜像下载的时候,尝试使用的加速地址,一般不需要修改,因为预载的系统镜像都是本组织下的仓库,这些cdn足够进行加速下载了 - -```shell -mysql: - auto-create: true - config: charset=utf8mb4&parseTime=True&loc=Local - db-name: oneclickvirt - engine: InnoDB - log-mode: error - log-zap: false - max-idle-conns: 10 - max-lifetime: 3600 - max-open-conns: 100 - password: "" - path: - port: - prefix: "" - singular: false - username: root -``` - -初始化的判断如果这块的```path```和```port```都为空,则判断需要进行初始化,此时你填入的初始化的数据库务必保证是空数据库。 - -```shell -quota: - default-level: 1 - instance-type-permissions: - min-level-for-container: 1 - min-level-for-delete: 2 - min-level-for-vm: 1 - level-limits: - 1: - max-instances: 1 - max-resources: - bandwidth: 10 - cpu: 1 - disk: 1025 - memory: 350 - max-traffic: 102400 - 2: - max-instances: 3 - max-resources: - bandwidth: 20 - cpu: 2 - disk: 20480 - memory: 1024 - max-traffic: 204800 - 3: - max-instances: 5 - max-resources: - bandwidth: 50 - cpu: 4 - disk: 40960 - memory: 2048 - max-traffic: 307200 - 4: - max-instances: 10 - max-resources: - bandwidth: 100 - cpu: 8 - disk: 81920 - memory: 4096 - max-traffic: 409600 - 5: - max-instances: 20 - max-resources: - bandwidth: 200 - cpu: 16 - disk: 163840 - memory: 8192 - max-traffic: 512000 -``` - -这块是等级与配额限制的配置项,内存、硬盘、流量的默认单位为```mb```,```min-level```配置是配置系统配置中的最低权限,默认最低等级1可开设容器,等级2可在普通用户端删除操作,默认等级1可开设虚拟机,```default-level```是默认的注册的用户的等级。 - -```shell -zap: - compress-logs: true - director: storage/logs - encode-level: LowercaseLevelEncoder - format: console - level: info - log-in-console: false - max-array-elements: 5 - max-backups: 15 - max-file-size: 5 - max-log-length: 2000 - max-string-length: 1000 - prefix: '[oneclickvirt]' - retention-day: 3 - show-line: false - stacktrace-key: stacktrace -``` - -这块唯一需要注意的是```level```字段,默认为```info```日志,如果需要调试日志,请改成```debug```。 +如果你需要额外类型的镜像,需要在管理员权限下,在系统镜像管理界面按照类型、架构、版本搜索并进行启用。 +初始化后请立即修改默认的管理员的用户名密码,并禁用或删除默认启用的测试用户,这一部分可在管理员的用户管理页面进行操作。 \ No newline at end of file