From 34028d065b5952b61ff5c849b6ad30f760b17d2b Mon Sep 17 00:00:00 2001 From: vicanso Date: Thu, 26 Dec 2024 14:55:25 +0800 Subject: [PATCH] docs: update documents --- README.md | 12 +++++------- README_zh.md | 7 +++---- src/acme/lets_encrypt.rs | 8 +++++++- src/service/auto_restart.rs | 25 ++++++++++++------------- src/util/crypto.rs | 8 ++++---- 5 files changed, 31 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index f1833e0..5c7129e 100644 --- a/README.md +++ b/README.md @@ -25,20 +25,20 @@ flowchart LR ## Feature - The service supports configuring multiple Locations, filtering locations by host and path, and matching and selecting them one by one according to the weight -- Support regular form configuration to rewrite Path +- Supports regular expression configuration to rewrite path - Support transparent proxy - Support HTTP 1/2, including h2c - Support static, dns and docker label service discovery - Support grpc-web reverse proxy -- Configuration based on TOML format, the configuration method is very simple, and can be saved to files or etcd +- Configuration based on TOML format, the configuration is very simple, and can be saved to files or etcd - Supports more than 10 Prometheus indicators, pull and push mode - Opentelemetry supports w3c context trace and jaeger trace -- Frequently updated Upstream and Location related configuration adjustments take effect in 30 seconds, and after other application configurations are updated, the program is restarted gracefully without interruption +- Frequently updated config: upstream, location and plugin, which adjustments take effect in 10 seconds, and other config is updated, program will be restarted gracefully without interruption - Templated configuration of access logs, which supports more than 30 related attribute configurations, and various parameters and indicators can be specified as needed - Web UI for config, simple and easy to use - Support let's encrypt, just set the domain of http server - TLS certificates of different domain names can be served in the same service port, and the matching certificate is automatically selected according to servername -- Supports push of various events: lets_encrypt, backend_status, diff_config, restart, etc. +- Supports push events: lets_encrypt, backend_status, diff_config, restart, etc. - Many http plugins, such as cache service components, compression components with multiple compression algorithms, authentication components, limiting components, etc. - Provides statistical data at different stages, such as upstream_connect_time, upstream_processing_time, compression_time, cache_lookup_time and cache_lock_time, etc. @@ -71,15 +71,13 @@ RUST_LOG=INFO pingap -c=/opt/pingap/conf \ ## Docker -`cGluZ2FwOjEyMzEyMw==` is base64("pingap:123123") - ```bash docker run -it -d --restart=always \ -v $PWD/pingap:/opt/pingap \ -p 3018:3018 \ vicanso/pingap -c /opt/pingap/conf \ --autoreload \ - --admin=cGluZ2FwOjEyMzEyMw==@0.0.0.0:3018 + --admin=pingap:123123@0.0.0.0:3018 ``` ## Dev diff --git a/README_zh.md b/README_zh.md index 8f24bab..83a5928 100644 --- a/README_zh.md +++ b/README_zh.md @@ -21,17 +21,16 @@ flowchart LR - 服务支持配置多个Location，通过host与path筛选对应的location，按权重逐一匹配选择 - 支持正则形式配置重写Path，方便应用按前缀区分转发 -- 支持透明代理形式转发 - HTTP 1/2 的全链路支持，包括h2c的支持 - 支持静态配置、DNS以及docker label的三种服务发现形式 - 支持grpc-web反向代理 - 基于TOML格式的配置，配置方式非常简洁，可保存至文件或etcd - 支持10多个Prometheus指标，可以使用pull与push的形式收集相关指标 - Opentelemetry支持w3c context trace与jaeger trace的形式 -- 频繁更新的Upstream与Location相关配置调整准实时生效(30秒)，其它应用配置更新后，无中断式的优雅重启程序 +- 频繁更新的Upstream、Location以及Plugin相关配置调整准实时生效(10秒)且无任何中断请求，其它应用配置更新后，无中断式的优雅重启程序 - 访问日志的模板化配置，已支30多个相关属性的配置，可按需指定输出各种参数与指标 - WEB形式的管理后台界面，无需学习，简单易用 -- 开箱即用的let's encrypttls证书，仅需配置对应域名即可 +- 开箱即用的let's encrypttls证书，仅需配置对应域名即可，可在单一配置中使用多个子域名 - 不同域名的tls证书可使用在同一服务端口中，按servername自动选择匹配证书 - 支持各种事件的推送：lets_encrypt, backend_status, diff_config, restart等等 - 丰富的http插件，如高效的缓存服务组件、多种压缩算法的压缩组件、不同种类的认证组件、不同形式的限流组件等等 @@ -57,7 +56,7 @@ RUST_LOG=INFO pingap -c=/opt/pingap/conf -t \ ## 自动重启 -应用启动后，监听相关配置变化，若有变化则无中断式重启程序或热更新加载配置。`autoreload`参数表示如果只是upstream与location的配置变化，则准实时(30秒内)刷新对应配置生效，无需重启。 +应用启动后，监听相关配置变化，若有变化则无中断式重启程序或热更新加载配置。`autoreload`参数表示如果只是upstream与location的配置变化，则准实时(10秒内)刷新对应配置生效，无需重启。 ```bash RUST_LOG=INFO pingap -c=/opt/pingap/conf \ diff --git a/src/acme/lets_encrypt.rs b/src/acme/lets_encrypt.rs index fb6a29a..70b77ea 100644 --- a/src/acme/lets_encrypt.rs +++ b/src/acme/lets_encrypt.rs @@ -117,6 +117,7 @@ async fn do_update_certificates( } }, Err(e) => error!( + category = LOG_CATEGORY, error = e.to_string(), domains = domains.join(","), "renew certificate fail, it will be run again later" @@ -309,7 +310,11 @@ async fn new_lets_encrypt( message: e.to_string(), })?; - info!(token = challenge.token, "let's encrypt well known path",); + info!( + category = LOG_CATEGORY, + token = challenge.token, + "let's encrypt well known path", + ); challenges.push((identifier, &challenge.url)); } @@ -345,6 +350,7 @@ async fn new_lets_encrypt( tries += 1; match tries < 10 { true => info!( + category = LOG_CATEGORY, delay = format!("{delay:?}"), "Order is not ready, waiting" ), diff --git a/src/service/auto_restart.rs b/src/service/auto_restart.rs index bcc1ce1..5ad45b7 100644 --- a/src/service/auto_restart.rs +++ b/src/service/auto_restart.rs @@ -53,7 +53,7 @@ async fn diff_and_update_config( } let mut reload_fail_messages = vec![]; - let mut hot_realod_config = current_config.clone(); + let mut hot_reload_config = current_config.clone(); { // hot reload first, // only validate server.locations, locations, upstreams and plugins @@ -67,7 +67,7 @@ async fn diff_and_update_config( // set server locations for (name, server) in new_config.servers.iter() { if let Some(clone_server_conf) = - hot_realod_config.servers.get_mut(name) + hot_reload_config.servers.get_mut(name) { if server.locations != clone_server_conf.locations { clone_server_conf.locations.clone_from(&server.locations); @@ -77,11 +77,11 @@ async fn diff_and_update_config( } // set upstream, location and plugin value - hot_realod_config.upstreams = new_config.upstreams.clone(); - hot_realod_config.locations = new_config.locations.clone(); - hot_realod_config.plugins = new_config.plugins.clone(); + hot_reload_config.upstreams = new_config.upstreams.clone(); + hot_reload_config.locations = new_config.locations.clone(); + hot_reload_config.plugins = new_config.plugins.clone(); - // acem will create a let's encrypt service + // acme will create a let's encrypt service // so it can't be reloaded. let mut exists_acme = false; for (_, cert) in new_config.certificates.iter() { @@ -90,7 +90,7 @@ async fn diff_and_update_config( } } if !exists_acme { - hot_realod_config.certificates = new_config.certificates.clone(); + hot_reload_config.certificates = new_config.certificates.clone(); } // new_config.certificates @@ -246,7 +246,7 @@ async fn diff_and_update_config( if hot_reload_only { let (updated_category_list, original_diff_result) = - current_config.diff(&hot_realod_config); + current_config.diff(&hot_reload_config); debug!( updated_category_list = updated_category_list.join(","), original_diff_result = original_diff_result.join("\n"), @@ -257,7 +257,7 @@ async fn diff_and_update_config( return Ok(()); } // update current config to be hot reload config - set_current_config(&hot_realod_config); + set_current_config(&hot_reload_config); if !original_diff_result.is_empty() { webhook::send_notification(webhook::SendNotificationParams { category: webhook::NotificationCategory::DiffConfig, @@ -279,10 +279,10 @@ async fn diff_and_update_config( } // restart mode // update current config to be hot reload config - set_current_config(&hot_realod_config); + set_current_config(&hot_reload_config); // diff hot reload config and new config - let (_, new_config_result) = hot_realod_config.diff(&new_config); + let (_, new_config_result) = hot_reload_config.diff(&new_config); debug!( new_config_result = new_config_result.join("\n"), "hot reload config diff from new config" @@ -391,10 +391,9 @@ impl BackgroundService for ConfigObserverService { _ = shutdown.changed() => { break; } - // 逻辑并不完善，有可能因为变更处理中途又发生其它变更导致缺失 - // 因此还需配合fetch的形式比对 _ = period.tick() => { // fetch and diff update + // some change may be restart run_diff_and_update_config(self.only_hot_reload).await; } result = observer.watch() => { diff --git a/src/util/crypto.rs b/src/util/crypto.rs index 867aa93..f371ca7 100644 --- a/src/util/crypto.rs +++ b/src/util/crypto.rs @@ -47,13 +47,13 @@ pub fn aes_encrypt(key: &str, data: &str) -> Result { message: e.to_string(), } })?; - let ciphertext = + let cipher_text = cipher .encrypt(&PINGAP_NONCE, data.as_bytes()) .map_err(|e| Error::Aes { message: e.to_string(), })?; - Ok(base64_encode(&ciphertext)) + Ok(base64_encode(&cipher_text)) } pub fn aes_decrypt(key: &str, data: &str) -> Result { @@ -63,10 +63,10 @@ pub fn aes_decrypt(key: &str, data: &str) -> Result { message: e.to_string(), } })?; - let ciphertext = + let cipher_text = base64_decode(data).map_err(|e| Error::Base64Decode { source: e })?; let plaintext = cipher - .decrypt(&PINGAP_NONCE, ciphertext.as_ref()) + .decrypt(&PINGAP_NONCE, cipher_text.as_ref()) .map_err(|e| Error::Aes { message: e.to_string(), })?;