diff --git a/docs/img/system_architecture01.png b/docs/img/system_architecture01.png new file mode 100644 index 00000000..928758aa Binary files /dev/null and b/docs/img/system_architecture01.png differ diff --git a/docs/manual/maintenance/crash_recovery.md b/docs/manual/maintenance/crash_recovery.md new file mode 100644 index 00000000..5e14a105 --- /dev/null +++ b/docs/manual/maintenance/crash_recovery.md @@ -0,0 +1,75 @@ + +!!! info "企业版客户出现服务故障建议在企业客户支持群中联系客户成功团队获取及时帮助。" + +## 1 JumpServer 程序故障 + +当出现组件容器异常高负载或者当容器健康为 unhealthy 时可以通过以下方案临时恢复。 + +**方案一：重启故障容器** + +```bash +# 重启故障容器 或者通过 `jmsctl restart [core/celery/koko/chen/lion]` 重建容器。 +docker restart <容器名> +# 检查所有组件运行状态 +jmsctl status + +``` + +**方案二：全部重启** + +```bash +# 进入安装包目录 +cd /opt/jumpserver-ee-{{ jumpserver.tag }}-x86_64 +# 停止 JumpServer 所有服务 +./jmsctl.sh down +# 检查是否有未停止的容器 +docker ps -a +# 若有未停止的容器，执行强制停止并删除（替换 ID 为实际容器 ID） +docker kill ID +docker rm ID +# 启动 JumpServer 服务（若个别组件启动不成功，可稍等后再次执行启动命令） +./jmsctl.sh start +# 检查 JumpServer 启动状态 +./jmsctl.sh status +``` + +## 2 数据库故障 + +1. 备份数据库： + + ```bash + jmsctl backup_db + ``` + +2. 登录数据库服务器，停止 JumpServer 服务（避免数据写入冲突）： + + ```bash + jmsctl stop + ``` + +3. 检查数据库具体故障原因（如服务未启动、配置错误、磁盘空间不足等），针对性修复； +4. 修复完成后，启动数据库服务，再重启 JumpServer： + + ```bash + jmsctl start + ``` + +## 3 服务器宕机 + +1. 优先恢复服务器硬件/系统，确保服务器能正常运行； +2. 检查数据库状态（内置/外置），按照 [数据库故障](./crash_recovery.md) 的处理方式恢复数据库； +3. 启动相关依赖服务： + ```bash + # 若使用 Keepalived，启动 Keepalived 服务 + systemctl start keepalived + # 启动 JumpServer 服务 + jmsctl start + ``` +1. 通过 `jmsctl status` 检查服务状态。 + +## 4 安全建议 + +> 1. 定期备份 JumpServer 数据库，避免数据丢失导致业务中断，建议结合业务场景设置每日/每周备份频率。 +> 2. 定期备份 JumpServer 核心配置文件（如 `config.txt` 及各类组件配置文件），便于故障时快速恢复环境。 +> 3. 全局开启 MFA（多因素认证）功能，通过二次验证提升账户安全性，降低因密码泄露引发的安全风险。 +> 4. 开启账户备份计划，定期将关键账户信息备份至指定邮箱，作为账户异常时的应急逃生方案。 diff --git a/docs/manual/maintenance/daily_operations.md b/docs/manual/maintenance/daily_operations.md new file mode 100644 index 00000000..125ec404 --- /dev/null +++ b/docs/manual/maintenance/daily_operations.md @@ -0,0 +1,277 @@ +## 1 命令行工具 jmsctl + +JumpServer 默认的安装脚本位于 `<安装包解压路径>/jmsctl.sh`。同时，JumpServer 支持命令行工具 `jmsctl`。 + +> 注意：安装后 JumpServer 安装包可删除，但解压后的目录不可删除。 + +`jmsctl` 命令可以在服务器的任一目录执行，`./jmsctl.sh` 需要切换至安装目录下执行。 + +### 1.1 命令使用格式 + +- `jmsctl [COMMAND]` +- `./jmsctl [COMMAND]` (需切换至安装包解压目录下执行) + +### 1.2 命令参数详解 +| 命令 | 说明 | +| :--- | :--- | +| `jmsctl help` | 获取帮助 | +| `jmsctl start` | 启动 JumpServer 服务的所有容器 | +| `jmsctl stop` | 停止 JumpServer 服务的所有容器 | +| `jmsctl down` | 关闭并移除 JumpServer 服务的所有容器 | +| `jmsctl restart` | 重启 JumpServer 服务的所有容器 | +| `jmsctl status` | 查看 JumpServer 服务的容器运行状态 | +| `jmsctl backup_db` | 备份 JumpServer 数据库文件 | +| `jmsctl uninstall` | 卸载 JumpServer 服务（操作此项会删除所有与 JumpServer 相关的数据，操作前需谨慎） | +| `jmsctl restore_db` | 恢复数据库数据，使用备份的 SQL 文件来恢复数据库信息 | + +> 注意：`jmsctl restart/down` 命令会删除容器或重建容器。服务会中断，但持久化目录数据以及业务数据不受影响。 + +## 2 修改配置文件 + +### 2.1 配置文件详解 + +以下为 JumpServer 默认参数解释： +!!! tip "" + ```ini + # JumpServer configuration file example. + # 如果不了解用途可以跳过修改此配置文件, 系统会自动填入 + # 完整参数文档 https://docs.jumpserver.org/zh/v3/guide/env/ + + ################################## 镜像配置 ################################### + # 国内连接 docker.io 会超时或下载速度较慢, 开启此选项使用华为云镜像加速 + # 取代旧版本 DOCKER_IMAGE_PREFIX + # DOCKER_IMAGE_MIRROR=1 + + # 镜像拉取规则 Always, IfNotPresent + # Always 表示每次都会拉取最新镜像, IfNotPresent 表示本地不存在镜像时才会拉取 + # IMAGE_PULL_POLICY=Always + + ################################## 安装配置 ################################### + # JumpServer 数据库持久化目录, 默认情况下录像、任务日志都在此目录 + # 请根据实际情况修改, 升级时备份的数据库文件(.sql)和配置文件也会保存到该目录 + VOLUME_DIR=/data/jumpserver # JumpServer的持久化文件保存目录 + + # 加密密钥, 迁移请保证 SECRET_KEY 与旧环境一致, 请勿使用特殊字符串 + # (*) Warning: Keep this value secret. + # (*) 勿向任何人泄露 SECRET_KEY + SECRET_KEY=NzhhNzNiNDItNmE0OC0wNTc0LTZlYzYtMzk1Mzk2ZDNhNjQ5 # 系统用来加密解密的key + + # 组件向 core 注册使用的 token, 迁移请保持 BOOTSTRAP_TOKEN 与旧环境一致, + # 请勿使用特殊字符串 + # (*) Warning: Keep this value secret. + # (*) 勿向任何人泄露 BOOTSTRAP_TOKEN + BOOTSTRAP_TOKEN=NzhhNzNiNDItNmE0OC0wNTc0 # 其他组件用来向JumpServer注册使用的token + + # 日志等级 INFO, WARN, ERROR + LOG_LEVEL=ERROR # 日志级别，可以调整为DEBUG模式，输入更详细的日志信息，需注意产生的日志大小 + + # JumpServer 容器使用的网段, 请勿与现有的网络冲突, 根据实际情况自行修改 + DOCKER_SUBNET=192.168.250.0/24 # JumpServer相关的容器的IP地址 + + # ipv6 nat, 正常情况下无需开启 + # 如果宿主不支持 ipv6 开启此选项将会导致无法获取真实的客户端 ip 地址 + USE_IPV6=0 + DOCKER_SUBNET_IPV6=fc00:1010:1111:200::/64 + + ################################# DB 配置 ################################## + # 外置数据库需要输入正确的数据库信息, 内置数据库系统会自动处理 + # + DB_ENGINE=postgresql # 指定数据库类型，可选mysql/postgresql + DB_HOST=postgresql # 数据库的连接地址，当地址为postgresql时。默认拉起PostgreSQL容器。 + DB_PORT=5432 # 数据库的连接端口 + DB_USER=postgres # 数据库的连接用户 + DB_PASSWORD=1a703974685f00c6622fa5ea87 # 数据库的连接用户密码 + DB_NAME=jumpserver # 数据库的连接数据库，即写入JumpServer数据的数据库 + + # 如果外置 MySQL 需要开启 TLS/SSL 连接, 参考 https://docs.jumpserver.org/zh/v3/installation/security_setup/mysql_ssl/ + # DB_USE_SSL=true + + ################################# Redis 配置 ################################## + # 外置 Redis 需要请输入正确的 Redis 信息, 内置 Redis 系统会自动处理 + REDIS_HOST=redis # Redis数据库的连接地址，当地址为Redis时，默认拉起Redis容器。 + REDIS_PORT=6379 # Redis数据库的连接端口 + REDIS_PASSWORD=NzhhNzNiNDItNmE0OC0wNTc0LT # Redis数据库的连接密码 + + # 如果使用外置 Redis Sentinel, 请手动填写下面内容 + # REDIS_SENTINEL_HOSTS=mymaster/192.168.100.1:26379,192.168.100.1:26380,192.168.100.1:26381 + # REDIS_SENTINEL_PASSWORD=your_sentinel_password + # REDIS_PASSWORD=your_redis_password + # REDIS_SENTINEL_SOCKET_TIMEOUT=5 + + # 如果外置 Redis 需要开启 TLS/SSL 连接, 参考 https://docs.jumpserver.org/zh/v3/installation/security_setup/redis_ssl/ + # REDIS_USE_SSL=true + + ################################## 访问配置 ################################### + # 对外提供服务端口, 如果与现有服务冲突请自行修改 + HTTP_PORT=80 # JumpServer的Web界面访问端口 + + ################################# HTTPS 配置 ################################# + # 参考 https://docs.jumpserver.org/zh/v3/installation/proxy/ 配置 + # HTTPS_PORT=443 + # SERVER_NAME=your_domain_name + # SSL_CERTIFICATE=your_cert + # SSL_CERTIFICATE_KEY=your_cert_key + # + + # Nginx 文件上传下载大小限制 + CLIENT_MAX_BODY_SIZE=4096m + + ################################## 组件配置 ################################### + # 组件注册使用, 默认情况下向 core 容器注册, 集群环境需要修改为集群 vip 地址 + # + CORE_HOST=http://core:8080 # JumpServer项目的URL，API请求注册使用 + PERIOD_TASK_ENABLED=true + + # Core Session 定义, + # SESSION_COOKIE_AGE 表示闲置多少秒后 session 过期, + # SESSION_EXPIRE_AT_BROWSER_CLOSE=true 表示关闭浏览器即 session 过期 + # SESSION_COOKIE_AGE=86400 + SESSION_EXPIRE_AT_BROWSER_CLOSE=true + + # 可信任 DOMAINS 定义, + # 定义可信任的访问 IP, 请根据实际情况修改, 如果是公网 IP 请改成对应的公网 IP, + # DOMAINS="demo.jumpserver.org:443" + # DOMAINS="172.17.200.191:80" + # DOMAINS="demo.jumpserver.org:443,172.17.200.191:80" + DOMAINS="10.1.12.47:80" + + # 配置不需要启动的组件, 默认所有组件都会开启, 如果不需要某个组件可以通过设置 {组件名称}_ENABLED 为 0 关闭 + # CORE_ENABLED=0 + # CELERY_ENABLED=0 + # KOKO_ENABLED=0 + # LION_ENABLED=0 + # MAGNUS_ENABLED=0 + # CHEN_ENABLED=0 + # Lion 开启字体平滑, 优化体验 + JUMPSERVER_ENABLE_FONT_SMOOTHING=true + + ################################# XPack配置 ################################# + # XPack 包, 开源版本设置无效 + SSH_PORT=2222 # JumpServer的ssh方式访问的端口 + RDP_PORT=3389 # RDP协议连接资产使用的端口（Razor） + XRDP_PORT=3390 # RDP协议连接资产使用的端口（XRDP） + MAGNUS_MYSQL_PORT=33061 # JumpServer使用Magnus组件连接MySQL数据库时使用的端口 + MAGNUS_MARIADB_PORT=33062 # JumpServer使用Magnus组件连接Mariadb数据库时使用的端口 + MAGNUS_REDIS_PORT=63790 # JumpServer使用Magnus组件连接Redis数据库时使用的端口 + MAGNUS_POSTGRESQL_PORT=54320 # JumpServer使用Magnus组件连接PostgreSQL数据库时使用的端口 + MAGNUS_SQLSERVER_PORT=14330 # JumpServer使用Magnus组件连接SQL Server数据库时使用的端口 + MAGNUS_ORACLE_PORT=15210 # JumpServer使用Magnus组件连接Oracle数据库时使用的端口 + XRDP_ENABLED=0 + + ################################## 其他配置 ################################## + # 终端使用宿主 HOSTNAME 标识, 首次安装自动生成 + SERVER_HOSTNAME=jumpserver-v4 + + # 使用内置 SLB, 如果 Web 页面获取到的客户端 IP 地址不正确, 请将 USE_LB 设置为 0 + # USE_LB 设置为 1 时, 使用配置 proxy_set_header X-Forwarded-For $remote_addr + # USE_LB 设置为 0 时, 使用配置proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for + USE_LB=1 + + # 当前运行的 JumpServer 版本号, 安装和升级完成后自动生成 + CURRENT_VERSION=v4.10.6 + ``` + +> 其他参数（默认参数或其他可自行添加的参数）请参考：[系统参数说明](env.md) + +### 2.2 修改 config.txt + +JumpServer 的核心配置文件为 `config.txt`，默认位置：`/opt/jumpserver/config/config.txt`。 + +如需要在 JumpServer 运行过程中更改 `config.txt` 文件中的内容，需要通过 `jmsctl restart` 命令重启 JumpServer 服务。 + +### 2.3 修改其他配置文件 + +JumpServer 在运行过程中，修改其他配置文件中的所有参数，均需要重启 JumpServer 进行加载。例如： + +- nginx 的配置文件（`/opt/jumpserver/config/nginx/lb_http_server.conf`） +- MySQL 的配置文件（`/opt/jumpserver/config/mariadb/mariadb.cnf`） +- PostgreSQL 的配置文件（`/data/jumpserver/postgresql/data/postgresql.conf`） + +如需要在 JumpServer 运行过程中更改上述文件中的内容，需要通过 `jmsctl restart` 命令重启 JumpServer 服务。 + +> 注意:数据库更改操作建议提前备份数据。 + +## 3 数据库备份 + +JumpServer 运行中，为防止 JumpServer 系统故障导致数据丢失，需要定时对 JumpServer 数据库进行备份。 + +### 3.1 命令行工具备份 + +!!! tip "" + ```bash + jmsctl backup_db + ``` + +### 3.2 手动备份命令 + +#### MySQL 手动备份 + +> 注：内置数据库需要进入容器执行 + +!!! tip "" + ```bash + mysqldump -u$登录用户 -p$登录用户密码 jumpserver > jumpserver-$(date +"%Y-%m-%d").sql + ``` + +#### PostgreSQL 手动备份 + +> 注：内置数据库需要进入容器执行 + +!!! tip "" + ```bash + pg_dump -U $登录用户 -h localhost -d jumpserver -f jumpserver-$(date +"%Y-%m-%d").dump + ``` + +## 4 数据库恢复 + +当数据库节点宕机、升级失败或其他场景需要回滚数据库时，可参考以下操作。 + +> 注意：数据库回滚的前提是之前有进行数据库备份工作。 + +### 4.1 单节点数据库命令行工具恢复 + +!!! tip "" + ```bash + jmsctl restore_db + # 文件路径参数无法使用相对路径。被封文件默认位置在 /data/jumpserver/db_backup 目录下。 + ``` + +### 4.2 手动恢复命令 +#### MySQL 单节点数据库回滚 + +> 注：内置数据库需要进入容器执行 + +!!! tip "" + ```bash + # 1. 停止 JumpServer 服务 + jmsctl stop + + # 2. 恢复数据库 + mysql -u$登录用户 -p$登录用户密码 jumpserver < /path/to/backup/jumpserver-YYYY-MM-DD.sql + + # 3. 启动 JumpServer 服务 + jmsctl start + ``` + +#### PostgreSQL 单节点数据库回滚 + +> 注：内置数据库需要进入容器执行 + +!!! tip "" + ```bash + # 1. 停止 JumpServer 服务 + jmsctl stop + + # 2. 恢复数据库 + psql -U $登录用户 -h localhost -d jumpserver -f /path/to/backup/jumpserver-YYYY-MM-DD.dump + + # 3. 启动 JumpServer 服务 + jmsctl start + ``` +### 4.3 多节点数据库恢复 + +!!! info "企业版客户如果数据库架构复杂，建议在企业客户支持群中联系客户成功团队获取恢复帮助。" + +需要根据具体的数据库集群架构，参考对应数据库的集群恢复方案进行操作。 + + diff --git a/docs/manual/maintenance/env.md b/docs/manual/maintenance/env.md new file mode 100644 index 00000000..b922c6b0 --- /dev/null +++ b/docs/manual/maintenance/env.md @@ -0,0 +1,149 @@ +# 参数说明 + +!!! warning "注意" + - 修改 /opt/jumpserver/config/config.txt 配置文件后需要重启 JumpServer 服务以生效。 + +## 1 Core 参数说明 + +!!! tip "" + - Core 参数： + +| 参数名称 | 可选项 | 说明 | +| :----- | :----- | :----- | +| SECRET_KEY | - | 用于对敏感字段进行加解密的 Key | +| BOOTSTRAP_TOKEN | - | 用于组件向 Core 服务注册使用的 Token | +| DEBUG | true
false | Debug 模式，如果开启页面请求 API 报错时会显示更多信息 | +| DEBUG_DEV | true
false | Debug 开发模式，如果开启后端日志会显示更多信息 | +| LOG_LEVEL | DEBUG
INFO
WARNING
ERROR
CRITICAL | 日志级别 | +| DB_ENGINE | postgresql/mysql | 数据库引擎 | +| DB_NAME | - | 数据库名 | +| DB_HOST | - | 数据库地址 | +| DB_PORT | - | 数据库端口 | +| DB_USER| - | 数据库用户 | +| DB_PASSWORD | - | 数据库用户密码 | +| DB_USE_SSL | true
false | 数据库启用 SSL 方式 | +| REDIS_HOST | - | Redis 地址 | +| REDIS_PORT | - | Redis 端口 | +| REDIS_PASSWORD | - | Redis 密码 | +| REDIS_USE_SSL | true
false | Redis 启用 SSL 方式 | +| REDIS_SSL_KEY | - | Redis SSL Key | +| REDIS_SSL_CERT | - | Redis SSL Cert 证书 | +| REDIS_SSL_CA | - | Redis SSL CA Cert 证书 | +| REDIS_SSL_REQUIRED | - | Redis SSL 证书是否必须 | +| REDIS_SENTINEL_HOSTS | - | Redis 哨兵地址（多个地址使用 / 分割） | +| REDIS_SENTINEL_PASSWORD | - | Redis 哨兵密码 | +| REDIS_SENTINEL_SOCKET_TIMEOUT | - | Redis 哨兵 Socket 超时时间 | +| REDIS_DB_CELERY | 0-15 | Redis 库编号，Celery 任务使用 | +| REDIS_DB_CACHE | 0-15 | Redis 库编号，缓存使用 | +| REDIS_DB_SESSION | 0-15 | Redis 库编号，用户 Session 使用 | +| REDIS_DB_WS | - | Redis 库编号，WebSocket 使用 | +| TOKEN_EXPIRATION | - | 通过 API 创建用户 Token 的有效期
# 如果配置为空或者0，则默认值为 3600 | +| DEFAULT_EXPIRED_YEARS | - | 创建资源的默认过期年份，比如：授权规则
# 不允许修改 | +| SESSION_COOKIE_DOMAIN | - | 用户 Session Cookie 域，比如：fit2cloud.com | +| CSRF_COOKIE_DOMAIN | - | 用户 CSRF Cookie 域，默认与 SESSION_COOKIE_DOMAIN 保持一致 | +| SESSION_COOKIE_NAME_PREFIX | - | 用户 Session Cookie 名称的前缀
# 如果配置了 SESSION_COOKIE_DOMAIN 参数，会使用 `.` 前的值作为默认值，比如：fit2cloud | +| SESSION_COOKIE_AGE | - | 用户 Session Cookie 的有效期 | +| SESSION_EXPIRE_AT_BROWSER_CLOSE | true
false | 用户 Session 在浏览器关闭后过期 | +| CONNECTION_TOKEN_EXPIRATION | >= 5 * 60 | 有效期内 ConnectionToken 只能使用一次 | +| CONNECTION_TOKEN_EXPIRATION_MAX | - | 有效期内 ConnectionToken 可以多次使用 | +| CONNECTION_TOKEN_REUSABLE | true
false | ConnectionToken 是否可以多次使用 | +| AUTH_CUSTOM | true
false | 开启自定义用户认证 | +| AUTH_CUSTOM_FILE_MD5 | - | 自定义用户认证的文件 md5 值 | +| MFA_CUSTOM | true
false | 开启自定义 MFA 认证 | +| MFA_CUSTOM_FILE_MD5 | - | 自定义 MFA 认证的文件 md5 值 | +| AUTH_TEMP_TOKEN | true
false | 开启临时密码功能 | +| LOGIN_REDIRECT_TO_BACKEND | Direct（直接进入内部登录页面）
OpenID
CAS
SAML2
OAuth2 的服务提供商名称（系统设置） | 开启第三方认证后，不出现倒计时跳转页面直接跳转到认证服务，比如：OpenID | +| LOGIN_REDIRECT_MSG_ENABLED | true
false | 开启第三方跳转倒计时页面 | +| SYSLOG_ADDR | - | SysLog 服务地址 | +| SYSLOG_FACILITY | - | SysLog FACILITY | +| SYSLOG_SOCKTYPE | - | SysLog SockType | +| PERM_EXPIRED_CHECK_PERIODIC | - | 校验过期的资产授权规则并过期用户授权树的周期 | +| LANGUAGE_CODE | zh | zh
en
ja | 语言 | +| TIME_ZONE | - | 时区 | +| SESSION_COOKIE_SECURE | true
false | 用户 Session Cookie 安全模式，开启后只允许在 https 协议下发送 | +| CSRF_COOKIE_SECURE | true
false | 用户 CSRF Token 安全模式，开启后只允许在 https 协议下发送 | +| REFERER_CHECK_ENABLED | true
false | 开启 REFERER 校验 | +| CSRF_TRUSTED_ORIGINS | - | CSRF 同源信任，多个地址使用 `,` 分割 | +| SESSION_ENGINE | - | 用户 Session 引擎 | +| SESSION_SAVE_EVERY_REQUEST | true
false | 每个请求都要保存用户 Session | +| SESSION_EXPIRE_AT_BROWSER_CLOSE_FORCE | true
false | 浏览器关闭后强制过期用户 Session 会话 | +| SERVER_REPLAY_STORAGE | - | 服务端录像存储
比如：
{
'TYPE': 's3',
'BUCKET': '',
'ACCESS_KEY': '',
'SECRET_KEY': '',
'ENDPOINT': ''
}
# 组件上传录像到 Core 服务，Core 自动上传到配置的对象存储服务 | +| CHANGE_AUTH_PLAN_SECURE_MODE_ENABLED | true
false | 改密计划安全模式
启用后，不支持用户自己改自己；
禁用后，支持自己改自己；
比如 root 改 root | +| SECURITY_VIEW_AUTH_NEED_MFA | true
false | 需要校验 MFA | +| SECURITY_DATA_CRYPTO_ALGO | aes_ecb
aes_gcm
aes
gm_sm4_ecb
gm | 数据加密算法 | +| GMSSL_ENABLED | true
false | 开启国密算法（数据加密算法）
SECURITY_DATA_CRYPTO_ALGO
GMSSL_ENABLED
# 如果同时配置，优先使用 SECURITY_DATA_CRYPTO_ALGO | +| OPERATE_LOG_ELASTICSEARCH_CONFIG | - | 操作日志"变更字段"的存储ES配置
比如：
{
"INDEX": "",
"HOSTS": "",
"OTHER": "",
"IGNORE_VERIFY_CERTS": "",
"INDEX_BY_DATE": "",
"DOC_TYPE": ""
} | +| MAGNUS_ORACLE_PORTS | - | Magnus 组件需要监听的 Oracle 端口范围 | +| APPLET_DOWNLOAD_HOST | - | Applet 等软件的下载地址 | +| FTP_FILE_MAX_STORE | - | FTP 文件上传下载备份阈值，单位(M)，当值<=0时，不备份文件 | + + +## 2 KoKo 参数说明 +!!! tip "" + - KoKo 参数如下： + +| 参数名称 | 可选项 | 说明 | +| :----- | :----- | :----- | +| NAME | hostname | 主机名 | +| CORE_HOST | http://127.0.0.1:8080 | Jumpserver 项目的 Url，API 请求注册会使用 | +| BOOTSTRAP_TOKEN | '' | 预共享秘钥，请和JumpServer 配置文件中保持一致 | +| BIND_HOST | 0.0.0.0 | 启动时绑定的IP | +| SSHD_PORT | - | 监听的SSH端口号 | +| HTTPD_PORT | - | 监听的HTTP/WS端口号 | +| ACCESS_KEY | - | 项目使用的ACCESS KEY, 默认会注册,并保存到文件 | +| ACCESS_KEY_FILE | - | ACCESS KEY 保存的地址, 默认注册后会保存到该文件中 | +| LOG_LEVEL | DEBUG
INFO
WARNING
ERROR
CRITICAL | 日志级别 | +| SSH_TIMEOUT | - | SSH 连接超时时间(单位=秒)
# 如果用户服务器启用了 useDNS 这些参数，有可能登录时间超过 15S，需要修改此参数 | +| LANGUAGE_CODE | zh | zh
en
ja | 语言 | +| UPLOAD_FAILED_REPLAY_ON_START | true
false | 未上传录像遗留文件，启动时是否上传 | +| SFTP_SHOW_HIDDEN_FILE | true
false | SFTP 是否显示隐藏文件 | +| REUSE_CONNECTION | true
false | 是否复用同一用户的 SSH 连接 | +| ASSET_LOAD_POLICY | - | all 则用户资产缓存本地搜索分页；默认异步加载资产, 异步搜索分页 | +| ZIP_MAX_SIZE | - | Web Sftp 文件下载，zip 支持压缩的最大额度 (单位=M) | +| ZIP_TMP_PATH | - | Web Sftp 文件下载，zip压缩文件存放的临时目录 | +| CLIENT_ALIVE_INTERVAL | 30
0 | 用户 SSH 登录 KoKo 之后，KoKo 给 SSH Client 发送的心跳间隔，默认为30，0则表示不发送，保持登录用户连接不断开 | +| RETRY_ALIVE_COUNT_MAX | - | 登录资产之后，KoKo 向资产发送心跳包出现错误的重试次数，默认为3。
# 当网络不稳定时，可以数值可设置大一些。 | +| SHARE_ROOM_TYPE | local
redis | 会话监控和共享使用的方式 | +| REDIS_HOST | - | Redis 地址 | +| REDIS_PORT | - | Redis 端口 | +| REDIS_PASSWORD | - | Redis 密码 | +| REDIS_DB_ROOM | - | 选择的 Redis 库索引 | +| ENABLE_LOCAL_PORT_FORWARD | true
false | 是否开启本地转发 (目前仅对 VScode Remote SSH 有效果) | +| ENABLE_VSCODE_SUPPORT | true
false | 是否开启针对 VScode 的 Remote SSH 远程开发支持
# 前置条件: 必须开启 ENABLE_LOCAL_PORT_FORWARD | + +## 3 Lion 参数说明 +!!! tip "" + - Lion 参数如下： + +| 参数名称 | 可选项 | 说明 | +| :----- | :----- | :----- | +| NAME | hostname | 主机名 | +| CORE_HOST | http://127.0.0.1:8080 | Jumpserver 项目的 Url，API 请求注册会使用 | +| BOOTSTRAP_TOKEN | '' | 预共享秘钥，请和JumpServer 配置文件中保持一致 | +| BIND_HOST | 0.0.0.0 | 启动时绑定的IP | +| HTTPD_PORT | - | 监听的 HTTP/WS 端口号 | +| GUA_HOST | - | Guacd 项目 URL | +| GUA_PORT | - | Guacd 项目端口 | +| LOG_LEVEL | DEBUG
INFO
WARNING
ERROR
CRITICAL | 日志级别 | +| SHARE_ROOM_TYPE | local
redis | 会话监控和共享使用的方式 | +| REDIS_HOST | - | Redis 地址 | +| REDIS_PORT | - | Redis 端口 | +| REDIS_PASSWORD | - | Redis 密码 | +| REDIS_DB_ROOM | - | 选择的 Redis 库索引 | +| JUMPSERVER_DISABLE_ALL_COPY_PASTE | true
false | 全局禁用剪切板粘贴复制 | +| JUMPSERVER_DISABLE_ALL_UPLOAD_DOWNLOAD | true
false | 全局禁用上传下载 | +| JUMPSERVER_REMOTE_APP_UPLOAD_DOWNLOAD_ENABLE | true
false | 开启 Remote App 的上传下载 | +| JUMPSERVER_REMOTE_APP_COPY_PASTE_ENABLE | true
false | 开启 Remote App 的剪切板粘贴复制 | +| JUMPSERVER_COLOR_DEPTH | 低色 16位
真彩 24位
真彩 32位 | 颜色深度 | +| JUMPSERVER_DPI | 120
160
240 | 图像每英寸长度内的像素点数 | +| JUMPSERVER_DISABLE_AUDIO | true
false | 禁止声音 | +| JUMPSERVER_ENABLE_WALLPAPER | true
false | 启用墙纸 | +| JUMPSERVER_ENABLE_THEMING | true
false | 启用主题 | +| JUMPSERVER_ENABLE_FONT_SMOOTHING | true
false | 启用平滑字体 | +| JUMPSERVER_ENABLE_FULL_WINDOW_DRAG | true
false | 启用拖拽窗口时渲染全部内容 | +| JUMPSERVER_ENABLE_DESKTOP_COMPOSITION | true
false | 启用透明窗口和阴影等图形效果 | +| JUMPSERVER_ENABLE_MENU_ANIMATIONS | true
false | 启用菜单开关动画 | +| JUMPSERVER_DISABLE_BITMAP_CACHING | true
false | 禁用RDP的内置位图缓存功能 | +| JUMPSERVER_DISABLE_OFFSCREEN_CACHING | true
false | 禁用客户端中当前不可见的屏幕区域缓存 | +| JUMPSERVER_DISABLE_GLYPH_CACHING | true
false | 禁用RDP会话中的字形缓存 | +| JUMPSERVER_CLEAN_DRIVE_SCHEDULE_TIME | - | 定时清理挂载盘文件的时间间隔 (单位：小时) ，如果设置值 0，则不清理 | \ No newline at end of file diff --git a/docs/manual/maintenance/logs_inspection.md b/docs/manual/maintenance/logs_inspection.md new file mode 100644 index 00000000..331aa62f --- /dev/null +++ b/docs/manual/maintenance/logs_inspection.md @@ -0,0 +1,58 @@ +## 1 系统组件日志 + +JumpServer 的默认安装地址为 `/data/jumpserver`，具体安装地址可执行以下命令查看： + +```bash +cat /opt/jumpserver/config/config.txt | grep VOLUME_DIR +``` + +本次示例以 `/data/jumpserver/` 为例： + +JumpServer 的核心日志存放在 `/data/jumpserver/core/data/logs`。 + +**核心日志文件详细介绍** + +| 日志文件名 | 说明 | +| :--- | :--- | +| `ansible.log` | ansible 执行任务产生的日志（linux 测试资产可连接性、更新硬件信息、推送系统用户、linux 执行改密计划等） | +| `beat.log` | 定时任务的日志 | +| `celery_ansible.log` | 异步任务 ansible 队列下的任务日志 | +| `celery_default.log` | 异步任务默认队列下的任务日志 | +| `drf_exception.log` | 使用 DRF 框架抛出的异常信息 | +| `flower.log` | 作业中心的任务监控组件日志 | +| `gunicorn.log` | 用来记录请求的日志 | +| `jumpserver.log` | JumpServer 的总日志 | +| `unexpected_exception.log` | JumpServer 报错信息日志 | + +**其他组件的日志文件位置** + +| 组件名称 | 日志文件路径 | +| :--- | :--- | +| Celery | `/data/jumpserver/celery/data/logs` | +| Lion | `/data/jumpserver/lion/data/logs` | +| Koko | `/data/jumpserver/koko/data/logs` | +| Razor| `/data/jumpserver/razor/data/logs` | +| Xrdp | `/data/jumpserver/xrdp/data/logs` | +| Chen | `/data/jumpserver/chen/data/logs` | +| Magnus | `/data/jumpserver/magnus/data/logs` | +| Web | `/data/jumpserver/web/data/logs` | +| Facelive | `/data/jumpserver/facelive/data/logs` | +| Nec | `/data/jumpserver/nec/data/logs` | + +## 2 Docker 日志查看 + +**示例：查看 core 容器的后 100 行日志** + +```bash +docker logs -f jms_core --tail 100 +``` + +**查看其他组件的实时日志** + +```bash +# 通过容器 ID 查看 +docker logs -f [Container ID] + +# 通过容器名称查看 +docker logs -f [Container name] +``` \ No newline at end of file diff --git a/docs/manual/maintenance/service_port.md b/docs/manual/maintenance/service_port.md new file mode 100644 index 00000000..75ba6139 --- /dev/null +++ b/docs/manual/maintenance/service_port.md @@ -0,0 +1,58 @@ +## 1 服务端口说明 + +JumpServer 服务涉及到的端口分为三个部分： + +- JumpServer 服务器端口； +- 数据库服务器端口；（当 PostgreSQL 与 Redis 为内置时，该模块取消） +- 被纳管的资产端口； + +### 1.1 JumpServer 服务器端口 + +JumpServer 部署成功后，需要开放的端口如下： + +| 端口 | 作用 | 说明 | 是否必须开通 | +| :--- | :--- | :--- | :--- | +| 80、443 | Web 端访问，http、https 服务端口 | http、https 服务端口 | 需要 | +| 2222 | SSH（堡垒机用户） | koko 服务组件默认端口，如果启用 SSH Client 方式访问堡垒机及登录资产，则需要开启 | 按需 | +| 3389 | Windows 资产的 RDP 方式连接端口 | Razor 服务组件默认端口，如果需要 RDP 方式访问 Windows 资产，则需要开启 | 按需 | +| 33061、33062、54320、63790、14330、15210 | Magnus 服务端口 | Magnus 服务组件默认端口，如果启用 DB 组件，则需要开启 | 按需 | + +### 1.2 数据库服务器端口 + +如 JumpServer 与数据库服务解耦，则数据库节点需要开放的端口如下： + +| 端口 | 作用 | 说明 | 是否必须开通 | +| :--- | :--- | :--- | :--- | +| 3306 | 数据库服务端口（MySQL） | MySQL 服务使用，存放 JumpServer 服务数据 | 是 | +| 5432 | 数据库服务端口（PostgreSQL） | PostgreSQL 服务使用，存放 JumpServer 服务数据 | 是 | +| 6379 | Redis 服务端口 | Redis 服务使用，存放 JumpServer 缓存数据 | 是 | + +### 1.3 资产端口 + +以下表格中的协议开放针对于 JumpServer 中纳管的资产，即需要开通 JumpServer 服务对该资产的访问端口。开放端口的操作在资产上进行。 + +| 协议类型 | 对应端口 | 作用 | 说明 | +| :--- | :--- | :--- | :--- | +| SSH 协议 | 默认端口为 22 | JumpServer 通过 SSH 协议连接资产时使用 | 根据资产实际使用 SSH 协议端口做规则放行 | +| RDP 协议 | 默认端口为 3389 | JumpServer 通过 RDP 协议连接资产时使用 | 根据资产实际使用 RDP 协议端口做规则放行 | +| VNC 协议 | 默认端口为 5900 | JumpServer 通过 VNC 协议连接资产时使用 | 根据资产实际使用 VNC 协议端口做规则放行 | +| Telnet 协议 | 默认端口为 23 | JumpServer 通过 telnet 协议连接资产时使用 | 根据资产实际使用 Telnet 协议端口做规则放行 | +| 其他协议 | 类似于 MySQL，默认为 3306；
类似于 HTTPS，默认为 443 | JumpServer 通过对应的协议连接资产时使用 | 根据资产实际使用的协议端口做规则放行 | + +## 2 防火墙配置说明 + +在生产环境部署时，如有防火墙以及网络限制应提前开放 JumpServer 相应的访问端口。 + +当 JumpServer 环境运行中需要添加 JumpServer 节点服务器防火墙策略以及修改机器网络配置等，需要重启 docker 服务以及 JumpServer 服务。操作步骤如下： +1. 修改防火墙策略或修改机器网络配置； +2. 重启 docker 服务； +3. 重启 JumpServer 服务。 + +!!! tip "" + ```bash + # 修改网络相关配置（根据实际需求执行） + # 重启 docker 服务 + systemctl restart docker + # 重启 JumpServer 服务 + jmsctl restart + ``` \ No newline at end of file diff --git a/docs/manual/maintenance/system_architecture.md b/docs/manual/maintenance/system_architecture.md new file mode 100644 index 00000000..93aa0d69 --- /dev/null +++ b/docs/manual/maintenance/system_architecture.md @@ -0,0 +1,63 @@ +# 系统架构说明 + +## 1 概述 + +JumpServer 堡垒机采用微服务架构设计。JumpServer 服务由 Docker 承载，不同的功能模块在不同的容器上面运行；通过 Docker-Compose 以及 jmsctl 管理脚本编排整个 JumpServer 服务的运行与维持不同功能模块之间的依赖关系。 + +!!! tips "" + 企业版安装包格式：`jumpserver-ee-{{ jumpserver.tag }}-x86_64.tar` [jumpserver-ee-系统版本-系统架构] + +## 2 依赖组件 + +JumpServer 堡垒机依赖组件如下： + +| 组件名称 | 组件描述 | +| :--- | :--- | +| jms_web | 该组件是 JumpServer 的高性能 HTTP 和反向代理 Web 服务器。 | +| jms_core | 该组件是 JumpServer 的核心组件，主要功能是鉴权和授权中心。| +| jms_celery | 该组件是 JumpServer 的任务调度服务器。 | +| jms_koko | 该组件是 JumpServer 的资产连接组件，以命令行的方式连接 Linux、K8S、数据库等资产。 | +| jms_lion | 该组件是 JumpServer 的资产连接组件，通过浏览器 Web 终端连接 Windows 资产。 | +| jms_chen | 该组件是 JumpServer 的资产连接组件，通过浏览器 Web 终端连接数据库。 | +| jms_magnus | 该组件是 JumpServer 的资产连接组件，通过数据库代理的方式支持用户通过原生的客户端（例如:Navicat、DBeaver 等）对数据库进行直连操作（X-PACK）。 | +| jms_razor | 该组件是 JumpServer 的资产连接组件，通过 JumpServer 客户端的方式拉起个人 PC 原生的远程连接工具 MSTSC，访问 Windows 资产。 | +| jms_xrdp | 该组件是 JumpServer 的资产连接组件，支持对 Windows 2003 版本的资产进行连接，审计。 | +| jms_facelive | 该组件是 JumpServer 支持通过人脸识别进行 MFA 认证的组件。 | +| jms_panda | 该组件是 JumpServer 的 Linux 远程应用发布机的支持组件。 | +| jms_video | 该组件是 JumpServer 的录像转换 MP4 组件。 | +| jms_nec | 该组件是服务于客户端方式连接 VNC 协议资产的组件。 | +| PostgreSQL | 提供数据库服务，存储 JumpServer 核心信息。如果无法提供外置 PostgreSQL，JumpServer 自动运行容器 jms_postgresql。 | +| Redis | 提供数据库信息缓存服务。如果无法提供外置 Redis，JumpServer 自动运行容器 jms_redis。 | + +## 3 文件夹用途介绍 + +JumpServer 的默认安装路径为 `/data/jumpserver`，具体的环境安装路径可通过查看配置文件获取。具体命令如下： + +```bash +cat /opt/jumpserver/config/config.txt | grep VOLUME_DIR +``` + +**主要目录与作用解释：** + +| 目录路径 | 作用 | +| :--- | :--- | +| `/opt/jumpserver/config/` | 该目录下保存了各个组件的配置信息。最主要的配置信息为该目录下的 `config.txt` 文件，该文件中保存的是 JumpServer 的核心配置。 | +| `$VOLUME_DIR/core/data/celery/` | 该目录下保存的是异步任务 ansible 队列下的任务日志。此目录下有两层子目录。日志文件最终会以任务 ID 的前两位选择相应的子目录进行存放，日志文件最终以 ID+.log 命名。
例如：任务 ID 为：
`6a942d0a-52ab-4704-beae-137465ca3eca`；
该任务生成的日志文件为：
`6a942d0a-52ab-4704-beae-137465ca3eca.log`；
存放的路径为：
`$VOLUME_DIR/core/data/celery/6/a/` 目录下； | +| `$VOLUME_DIR/core/data/logs/` | 该目录下保存的是 JumpServer 的日志文件。日志文件详细介绍如下：
- `ansible.log`：该日志是 ansible 执行自动化任务产生的日志（测试资产可连接性、更新硬件信息、推送账户、执行改密计划等）；
- `beat.log`：该日志是定时任务的日志；
- `celery_ansible.log`：该日志是异步任务 ansible 队列下的任务日志；
- `celery_default.log`：该日志是异步任务默认队列下的任务日志；
- `celery.log`：该日志是 celery 组件的日志；
- `daphne.log`：该日志是 Django 的一部分，主要用来支持 websocket；
- `drf_exception.log`：该日志是使用 DRF 框架抛出的异常信息；
- `flower.log`：该日志是作业中心的任务监控组件日志；
- `gunicorn.log`：该日志是用来记录 API 请求的日志；
- `jumpserver.log`：该日志是 JumpServer 的总日志。 | +| `$VOLUME_DIR/core/data/media/` | 该目录下存放的是远程应用源文件、录像文件、文件上传下载的文件以及自定义的 LOGO 文件等。 | +| `$VOLUME_DIR/core/data/ops/` | 该目录下存放的是用户上传的 playbook 文件。 | +| `$VOLUME_DIR/core/data/static/` | 该目录下存放的是 JumpServer 运行过程中需要的静态文件，例如：img、CSS、js 文件等。 | +| `$VOLUME_DIR/组件名称/data/certs/` | 组件需要的证书信息。 | +| `$VOLUME_DIR/组件名称/data/ftp_files/` | 该目录下临时存放的是通过该组件上传下载的文件内容。 | +| `$VOLUME_DIR/组件名称/data/keys/` | 该目录下存放的是该组件与 core 组件注册时使用的秘钥。 | +| `$VOLUME_DIR/组件名称/data/logs/` | 该目录下存放的是该组件的日志信息。 | +| `$VOLUME_DIR/组件名称/data/replays/` | 该目录下存放的是该组件正在产生的一些会话信息，在该会话结束后，此录像文件会发送给 core 组件。 | +| `$VOLUME_DIR/db_backup` | 该目录下存放的是 JumpServer 数据库的备份文件以及 JumpServer 配置文件的备份。 | +| `$VOLUME_DIR/postgresql/` | 该目录下存放的是 PostgreSQL 的持久化文件（内置数据库） | +| `$VOLUME_DIR/redis/` | 该目录下存放的是 Redis 的配置文件及持久化文件(内置 redis ) | + +## 4 服务运行状态 + +JumpServer 堡垒机的模块都是独立打包和运行的，基于微服务的架构和容器化部署。可以通过 `jmsctl status` 命令获取当前组件容器的运行状态。 + +![image](../../img/system_architecture01.png) \ No newline at end of file diff --git a/docs/manual/maintenance/system_upgrade.md b/docs/manual/maintenance/system_upgrade.md new file mode 100644 index 00000000..1b97a336 --- /dev/null +++ b/docs/manual/maintenance/system_upgrade.md @@ -0,0 +1,99 @@ + +!!! info "企业版客户如果架构复杂，建议在企业客户支持群中联系客户成功团队获取升级帮助。" + +> 注意：
+> 1. 如您的环境需要升级，建议首先查看官方网站的 release note，了解近期版本变化，选择适合当前环境的版本。
+> 2. JumpServer 服务升级过程中服务会停止一段时间（根据环境情况，时间为 10~30 分钟），建议至少申请一个小时的变更窗口，留足验证以及回退时间。 + + +JumpServer 升级服务采用一键快速升级方式，此过程会重启整个 JumpServer 平台的所有服务，并自动变更数据库表结构； + +## 1 单节点升级步骤 + +### 1.1 下载并上传安装包 + +- 企业版安装包在飞致云 support 门户中下载最新安装包或在企业支持群中联系相关客户成功团队获取。 + +!!! tips "" + - 注意：企业版安装包与社区版安装包不同，请勿混用。 + - 企业版安装包格式：`jumpserver-ee-{{ jumpserver.tag }}-x86_64.tar` [jumpserver-ee-系统版本-系统架构] + +下载完成后，需要上传安装包至服务器后台。 + +### 1.2 备份原环境服务数据 + +```bash +jmsctl backup_db +``` + +### 1.3 解压安装包并进入新版本安装包目录 + +```bash +tar -xf jumpserver-ee-{{ jumpserver.tag }}-x86_64.tar.gz +cd jumpserver-ee-{{ jumpserver.tag }}-x86_64/ +``` + +### 1.4 执行升级脚本 +!!! warning "此步骤需要进入新版本安装包内执行，请注意路径。" + +```bash +./jmsctl.sh upgrade +``` + +### 1.5 启动 JumpServer 服务 + +```bash +./jmsctl.sh start +``` + +## 2 多节点升级步骤 + +!!! info "企业版客户如果架构复杂，建议在企业客户支持群中联系客户成功团队获取升级帮助。" + +### 1.1 下载并上传安装包 + +- 企业版安装包在飞致云 support 门户中下载最新安装包或在企业支持群中联系相关客户成功团队获取。 + +!!! tips "" + - 注意：企业版安装包与社区版安装包不同，请勿混用。 + - 企业版安装包格式：`jumpserver-ee-{{ jumpserver.tag }}-x86_64.tar` [jumpserver-ee-系统版本-系统架构] + +下载完成后，需要上传安装包至各个节点服务器后台。 + +### 1.2 备份原环境服务数据 + +```bash +jmsctl backup_db +``` + +### 1.3 停止各个节点的 JumpServer 服务 + +```bash +jmsctl stop +``` + +### 1.4 解压安装包并进入新版本安装包目录 + +```bash +tar -xf jumpserver-ee-{{ jumpserver.tag }}-x86_64.tar.gz +cd jumpserver-ee-{{ jumpserver.tag }}-x86_64/ +``` + +### 1.5 主节点执行升级脚本（不能同时升级，以免数据库表结构变更冲突） +!!! warning "此步骤需要进入新版本安装包内执行，请注意路径。" + +```bash +./jmsctl.sh upgrade +``` + +### 1.6 其余节点分别进行升级 + +```bash +./jmsctl.sh upgrade +``` + +### 1.7 启动各个节点服务 + +```bash +./jmsctl.sh start +``` \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index ccce2508..8a68a0f3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -185,6 +185,15 @@ nav: - 客户端下载与安装: manual/client/client_installation.md - 资产连接: manual/client/asset_connection.md - 连接设置: manual/client/connection_settings.md + + - 运维手册: + - 系统架构说明: manual/maintenance/system_architecture.md + - 服务端口说明: manual/maintenance/service_port.md + - 日常基本操作: manual/maintenance/daily_operations.md + - 日志查看操作: manual/maintenance/logs_inspection.md + - 系统升级操作: manual/maintenance/system_upgrade.md + - 故障恢复操作: manual/maintenance/crash_recovery.md + - 系统参数说明: manual/maintenance/env.md