From 52bf807ab04343a979316a50c05e36d2120dfc96 Mon Sep 17 00:00:00 2001 From: JK Date: Fri, 6 Feb 2026 03:50:16 +0900 Subject: [PATCH 1/7] =?UTF-8?q?refactor:=20=EC=84=A4=EC=B9=98=20=EB=AC=B8?= =?UTF-8?q?=EC=84=9C=20=EA=B5=AC=EC=A1=B0=20=EA=B0=9C=EC=84=A0=20=EB=B0=8F?= =?UTF-8?q?=20=EC=9D=BC=EA=B4=80=EC=84=B1=20=ED=96=A5=EC=83=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 메인 페이지(installation.mdx) 재구성: 빠른 시작, 설치 가이드, 참조 문서로 논리적 흐름 개선 - 누락된 문서 링크 추가 (post-installation-setup, product-versions 등) - 모든 문서의 섹션 제목 수준을 일관되게 조정 (### → ##) - prerequisites.mdx: 요약 테이블 추가, 중복된 서버 사양을 참조 링크로 대체 - installation.mdx: 설치 방법 선택 테이블 추가 - post-installation-setup.mdx: 설정 체크리스트 테이블 추가 - license-installation.mdx: 버전별 관리 방법 명확화 - server-configuration-requirements.mdx: 빠른 참조 테이블 추가 Co-Authored-By: Claude Opus 4.5 --- src/content/ko/installation.mdx | 48 +++++++++-- .../container-environment-variables.mdx | 15 ++-- src/content/ko/installation/installation.mdx | 58 ++++++++------ .../ko/installation/license-installation.mdx | 80 +++++++++---------- .../installation/post-installation-setup.mdx | 29 ++++--- src/content/ko/installation/prerequisites.mdx | 52 ++++++------ .../ko/installation/product-versions.mdx | 12 +-- .../server-configuration-requirements.mdx | 19 ++++- ...rchitecture-and-network-access-control.mdx | 32 ++++---- 9 files changed, 202 insertions(+), 143 deletions(-) diff --git a/src/content/ko/installation.mdx b/src/content/ko/installation.mdx index 5b6d42c09..9fef67501 100644 --- a/src/content/ko/installation.mdx +++ b/src/content/ko/installation.mdx @@ -4,18 +4,50 @@ title: '제품 설치' # 제품 설치 -QueryPie ACP 는 모든 버전에 대해 사전 빌드된 Docker 이미지를 제공하며, Public Cloud 의 Linux VM 또는 On-Premise 환경의 리눅스 서버 환경에서, 쉽고 빠르게 설치할 수 있습니다. -설치를 위한 인스턴스의 사양으로 4 vCPU, 16 GiB Memory, 100 GiB 이상의 Disk 공간을 권장합니다. +QueryPie ACP는 Docker 이미지로 제공되며, Public Cloud의 Linux VM 또는 On-Premise 환경에서 설치할 수 있습니다. -상세한 설치 안내는 다음의 문서를 참조하세요: +## 빠른 시작 -* [설치 전 준비사항](installation/prerequisites) -* [설치하기](installation/installation) +처음 사용하시는 분은 Community Edition으로 시작하는 것을 권장합니다. + +* [QueryPie ACP Community Edition](installation/querypie-acp-community-edition) - 5명 이하의 사용자를 위한 무료 버전 + * [MCP 설정 가이드](installation/querypie-acp-community-edition/mcp-configuration-guide) + +## 설치 가이드 + +설치 과정은 다음 순서로 진행합니다. + +### 1. 설치 전 준비 + +* [설치 전 준비사항](installation/prerequisites) - 서버 환경, 컨테이너 엔진, 네트워크 요구사항 + * [리눅스 배포본과 Docker, Podman 지원 현황](installation/prerequisites/linux-distribution-and-docker-podman-support-status) + * [Podman으로 Rootless Mode 구성하기](installation/prerequisites/configuring-rootless-mode-with-podman) + +### 2. 설치하기 + +* [설치하기](installation/installation) - 설치 방법 개요 + * [설치 가이드 - setup.v2.sh](installation/installation/installation-guide-setupv2sh) - 권장하는 자동화 설치 방법 + * [설치 가이드 - 간단한 구성](installation/installation/installation-guide-simple-configuration) - 수동 설치 방법 + * [setup.sh, setup.v2.sh 비교](installation/installation/comparison-of-setupsh-and-setupv2sh) + * [AWS EKS 환경에서 설치하기](installation/installation/installing-on-aws-eks) - Kubernetes 환경 설치 + +### 3. 설치 후 설정 + +* [라이선스 설치](installation/license-installation) +* [설치 후 초기 설정](installation/post-installation-setup) - Web Base URL, Proxy 주소 설정 + +## 참조 문서 + +설치 및 운영에 필요한 상세 정보입니다. + +* [제품 버전](installation/product-versions) - 설치 가능한 버전 정보 * [시스템 아키텍처와 네트워크 접근제어](installation/system-architecture-and-network-access-control) * [컨테이너 환경변수](installation/container-environment-variables) -* [라이선스 설치](installation/license-installation) + * [DB_MAX_CONNECTION_SIZE 최적화](installation/container-environment-variables/optimizing-dbmaxconnectionsize) + * [QUERYPIE_WEB_URL](installation/container-environment-variables/querypieweburl) * [서버구성 요구사항](installation/server-configuration-requirements) -* [QueryPie ACP Community Edition](installation/querypie-acp-community-edition) - * [MCP 설정 가이드](installation/querypie-acp-community-edition/mcp-configuration-guide) + * [서버구성 요구사항 요약표](installation/server-configuration-requirements/server-configuration-requirements-summary) + * [Public Cloud 운영서버 요구사항](installation/server-configuration-requirements/public-cloud-production-server-requirements) + * [On-Premise VM 요구사항](installation/server-configuration-requirements/on-premise-vm-requirements) diff --git a/src/content/ko/installation/container-environment-variables.mdx b/src/content/ko/installation/container-environment-variables.mdx index e90588b2a..96d7ba69d 100644 --- a/src/content/ko/installation/container-environment-variables.mdx +++ b/src/content/ko/installation/container-environment-variables.mdx @@ -6,10 +6,13 @@ import { Callout } from 'nextra/components' # 컨테이너 환경변수 -QueryPie ACP 의 Server Container 를 실행하는데 필요한 환경변수에 대한 안내를 제공합니다. -이 문서는 QueryPie 10.3.0 또는 이후 버전에 적용됩니다. +QueryPie Server Container를 실행하는 데 필요한 환경변수를 안내합니다. -### 기본 환경변수 + +이 문서는 QueryPie 10.3.0 이상 버전에 적용됩니다. + + +## 기본 환경변수 | **Environment Variable Name** | **Default Value** | **Description** | | ------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -30,7 +33,7 @@ QueryPie ACP 의 Server Container 를 실행하는데 필요한 환경변수에 | DAC_SKIP_SQL_COMMAND_RULE_FILE | `skip_command_config.json` | 3rd Party Tool (DataGrip, DBeaver 등 워크벤치 툴) 에서 이용자가 입력하는 쿼리가 아닌, 툴이 자동으로 실행하는 SQL Query 를 Audit Log 에 남기지 않도록 설정합니다.툴이 자동으로 실행하는 SQL Query 는 구문의 패턴이 정해져 있다는 의미에서, 정형화된 Query 라고 부르기도 합니다.이러한 정형화된 Query 를 Audit Log 에 남기지 않도록 설정하면, 이용자가 체감하는 3rd Party Tool 의 응답속도가 빨라지게 됩니다. QueryPie Server 의 성능 부하를 감소시키는데, 도움이 됩니다.자세한 내용은 [Unknown Title#환경변수 추가.2](https://chequer.atlassian.net/wiki/spaces/QCP/pages/851346405/10.2.x#%ED%99%98%EA%B2%BD%EB%B3%80%EC%88%98-%EC%B6%94%EA%B0%80.2) 문서에서 확인할 수 있습니다. | -### 더이상 사용되지 않는 환경변수 +## 더 이상 사용되지 않는 환경변수 @@ -153,7 +156,7 @@ SAC > RDP(WinSAC) 세션 레코딩에 사용하는 이미지를 EC2 인스턴
-### FAQ +## FAQ #### Q: DB_HOST, REDIS_HOST 에 127.0.0.1 이나 localhost 를 사용할 수 있나요? @@ -234,7 +237,7 @@ Redis는 다음과 같은 목적으로 사용됩니다. 그 시점에 실행 중이던 특정 작업, 이용자 요청이 실패하게 됩니다. Redis 와 QueryPie Container 를 재시작하게 되면, QueryPie Container 가 정상적으로 작동하게 됩니다. -### 고급기능을 위한 환경변수 +## 고급 기능을 위한 환경변수 [Environment Variables for Advanced Setup - 10.3.x (KO)](https://querypie.atlassian.net/wiki/spaces/QCP/pages/954597480) 페이지를 참조하세요. diff --git a/src/content/ko/installation/installation.mdx b/src/content/ko/installation/installation.mdx index e57ade571..ae3d1b797 100644 --- a/src/content/ko/installation/installation.mdx +++ b/src/content/ko/installation/installation.mdx @@ -4,44 +4,54 @@ title: '설치하기' # 설치하기 -QueryPie ACP 제품을 설치하는 방법은 Container 실행방식, 설치 도우미 프로그램의 버전에 따라, 안내 문서가 구분되어 제공됩니다. +QueryPie ACP를 설치하는 방법을 안내합니다. 환경에 따라 적합한 설치 방법을 선택하세요. -### Compose Tool 로 Container 를 실행하기 +## 설치 방법 선택 -일반적인 설치, 실행 방법이며, 제조사에서 권장하는 설치 방법입니다. -Docker Compose 를 활용하여, Container Image 를 내려받고, 실행, 종료하는 방식입니다. +| 설치 방법 | 권장 대상 | 특징 | +| --- | --- | --- | +| [setup.v2.sh](installation/installation-guide-setupv2sh) | 신규 설치, Community Edition | 자동화된 설치, Docker Hub 사용 | +| [setup.sh](installation/installation-guide-simple-configuration) | 기존 고객, 파트너 | 수동 설치, Harbor Registry 사용 | +| [Kubernetes (EKS)](installation/installing-on-aws-eks) | 대규모 운영 환경 | Helm Chart 기반 설치 | -이 경우, 설치 도우미 프로그램의 버전에 따라, 두 가지 설치 방식이 제공됩니다. +## Docker Compose로 설치하기 -#### setup.v2.sh 로 설치하기 +Docker Compose를 활용하여 설치하는 방법으로, 대부분의 환경에서 권장합니다. -2025년 8월 출시된 QueryPie ACP Community Edition 의 출시와 함께 최종 고객사와 파트너 엔지니어에게 제공되는 설치 도우미 프로그램입니다. -Docker Hub 에 공개된 Container Image 를 내려받아 설치하는 방식입니다. +### setup.v2.sh로 설치하기 (권장) -설치 과정이 자동화되어, 처음 설치하는 이용자가 제품을 쉽게 설치할 수 있습니다. -setup.v2.sh 가 실제로 실행하는 설치 과정은 setup.sh 의 설치 방식과 동등합니다. -setup.v2.sh 는 그 과정이 자동화되었고, Version 10 등 구버전의 설치를 지원하지 않는다는 차이가 있습니다. -더 상세한 차이점은 이 문서를 참조하세요: [setup.sh, setup.v2.sh 비교](installation/comparison-of-setupsh-and-setupv2sh) +2025년 8월 출시된 자동화 설치 프로그램입니다. -Apple Silicon 을 사용하는 macOS 환경의 설치를 지원합니다. +**특징:** +* Docker Hub의 공개 이미지 사용 (별도 계정 불필요) +* 설치 과정 자동화 +* Podman + Rootless Mode 지원 +* macOS (Apple Silicon) 지원 -자세한 설치 방법은 이 문서를 참조하세요: [설치 가이드 - setup.v2.sh](installation/installation-guide-setupv2sh) +```bash +bash <(curl -s https://dl.querypie.com/setup.v2.sh) +``` -#### setup.sh 로 설치하기 +자세한 설치 방법: [설치 가이드 - setup.v2.sh](installation/installation-guide-setupv2sh) -QueryPie ACP Version 9 시절부터 파트너 엔지니어에게 제공된 설치 도우미 프로그램입니다. -Harbor 라는 Container Registry 에 계정을 발급받아 Container Image 를 내려받을 수 있습니다. +### setup.sh로 설치하기 -자세한 설치 방법은 이 문서를 참조하세요: [설치 가이드 - 간단한 구성](installation/installation-guide-simple-configuration) +기존 고객과 파트너를 위한 설치 프로그램입니다. -### Kubernetes 환경에 설치하기 +**특징:** +* Harbor Registry 계정 필요 +* 수동 설치 과정 +* Version 10 이전 버전 지원 -QueryPie ACP 는 Container 환경에서 작동하는 소프트웨어 제품입니다. -Compose Tool 을 이용해 설치, 실행하는 것이 일반적이지만, Kubernetes 환경에서도 매끄럽게 작동합니다. +자세한 설치 방법: [설치 가이드 - 간단한 구성](installation/installation-guide-simple-configuration) -Kubenetes 환경에서 제품을 설치하는 경우, AWS EKS, GCP GKE 등 Managed Kubernetes Cluster 와 Self-Hosted Cluster, 모두 사용 가능합니다. +두 설치 프로그램의 차이점: [setup.sh, setup.v2.sh 비교](installation/comparison-of-setupsh-and-setupv2sh) -* AWS EKS 환경 : [AWS EKS 환경에서 설치하기](installation/installing-on-aws-eks) -* Helm Chart : [https://github.com/chequer-io/querypie-deployment](https://github.com/chequer-io/querypie-deployment) +## Kubernetes 환경에 설치하기 + +AWS EKS, GCP GKE 등 Managed Kubernetes Cluster와 Self-Hosted Cluster에서 Helm Chart를 사용하여 설치합니다. + +* [AWS EKS 환경에서 설치하기](installation/installing-on-aws-eks) +* [Helm Chart Repository](https://github.com/chequer-io/querypie-deployment) diff --git a/src/content/ko/installation/license-installation.mdx b/src/content/ko/installation/license-installation.mdx index 531e0c513..f1179ac87 100644 --- a/src/content/ko/installation/license-installation.mdx +++ b/src/content/ko/installation/license-installation.mdx @@ -6,12 +6,17 @@ import { Callout } from 'nextra/components' # 라이선스 설치 -QueryPie 제품의 License 를 최초 설치, 업그레이드 설치하는 방법을 안내합니다. +QueryPie 라이선스를 설치하고 관리하는 방법을 안내합니다. -### QueryPie 를 처음 설치하는 경우11.3.0 + +**버전별 라이선스 관리 방법** +* 11.3.0 이상: Web Console에서 라이선스 관리 +* 11.3.0 미만: QueryPie Tools를 사용한 라이선스 설치 + + +## 처음 설치하는 경우 (11.3.0 이상) -QueryPie ACP 를 처음 설치하여 실행하는 경우, 웹브라우저로 웹콘솔에 접속하게 되면, 라이선스 입력을 요구합니다. -라이선스를 정상적으로 입력하게 되면, 로그인 화면을 만나게 됩니다. +QueryPie를 처음 설치하여 실행하면, 웹브라우저에서 라이선스 입력을 요구합니다.
PEM 형식 라이선스 입력 화면 @@ -20,26 +25,30 @@ PEM 형식 라이선스 입력 화면
-### 라이선스를 추가, 교체하기11.3.0 +## 라이선스 추가 및 교체 (11.3.0 이상) -11.3.0 또는 이후 버전에서는 웹콘솔에서 제품의 License 를 설치, 추가, 교체할 수 있습니다: [Licenses](../administrator-manual/general/company-management/licenses) +11.3.0 이상에서는 Web Console에서 라이선스를 관리할 수 있습니다. -#### 다수의 라이선스 설치 후 관리하기 +**설정 경로:** Admin Page → General → Company Management → [Licenses](../administrator-manual/general/company-management/licenses) -11.3.0 이전 버전에는 License 의 유효기간이 겹치는 라이선스를 추가 설치할 수 없는 제약이 있었으나, 11.3.0 부터는 유효기간이 겹치는 라이선스를 추가 설치할 수 있습니다. -유효한 라이선스가 둘 이상인 경우, 유효한 라이선스를 관리자가 지정할 수 있습니다. +### 라이선스 상태 -유효한 라이선스의 상태는 활성화 여부에 따라, 다음과 같이 구분됩니다. +| 상태 | 설명 | +| --- | --- | +| Activated | 현재 활성화된 라이선스 | +| Available | 사용 가능하지만 활성화되지 않은 라이선스 | -* Activated : 현재 활성화된 상태 -* Available : 사용 가능한 license이지만 활성화 하지 않은 상태 +11.3.0부터는 유효기간이 겹치는 라이선스도 추가 설치할 수 있습니다. -### QueryPie 를 처음 설치하는 경우Deprecated +## 11.3.0 미만 버전에서 라이선스 설치 -QueryPie 를 처음 설치하는 경우, QueryPie Tools 라는 컴포넌트를 실행하여, Product License 를 설치할 수 있습니다. -QueryPie Tools 는 QueryPie Server 와 별개로 작동하는 도구로, 제품 설치, 업그레이드, 라이선스 설치 등에 사용하는 도구입니다. + +이 섹션은 11.3.0 미만 버전 사용자를 위한 내용입니다. 11.3.0 이상에서는 Web Console을 사용하세요. + -QueryPie Tools 를 이용해 Product License 설치하는 방법을 간단히 설명하면 다음과 같습니다. +### 처음 설치하는 경우 + +QueryPie Tools를 실행하여 라이선스를 설치합니다. `docker-compose` 명령으로 QueryPie Tools Container 를 실행합니다. ``` @@ -61,7 +70,7 @@ ubuntu@querypie:~/querypie/10.2.4$ 전반적인 제품 설치 과정과 Product License 설치 단계에 대한 상세한 설명은 다음 문서를 참조하여 주세요: [설치 가이드 - 간단한 구성](installation/installation-guide-simple-configuration) -### 사용 중인 QueryPie 의 라이선스를 연장하는 경우Deprecated +### 라이선스 연장하는 경우 현재 사용 중인 QueryPie 에 라이선스를 연장하고자 하는 경우가 있습니다. 예를 들어, PoC 진행 중이던 QueryPie Server Instance 에 Production License 를 설치하여, 기존 PoC License 를 연장하고자 하는 경우를 가정합니다. @@ -97,25 +106,15 @@ ubuntu@querypie:~/querypie/10.2.4$ 이 응답 메시지를 만난 경우 대처 방법은, “사용 중인 QueryPie 의 라이선스를 교체하는 경우” 섹션을 참고하시기 바랍니다. -### 사용 중인 QueryPie 의 라이선스를 교체하는 경우Deprecated - -QueryPie 의 License 관리 기능에는 한가지 제약사항이 있어서, 기존 라이선스의 유효기간과 새 라이선스의 유효기간이 일부 겹치는 경우, 새 라이선스를 추가로 설치하지 못합니다. -이로 인해, 유효기간이 겹치는 라이선스를 설치하려는 경우, 별도 절차를 통하여 기존 라이선스를 삭제한 후, 새로운 라이선스를 설치하여야 합니다. +### 라이선스 교체하는 경우 (유효기간 중복 시) - -11.3.0 또는 이후 버전에는 이 제약이 해소되었습니다. -참조: [Licenses](../administrator-manual/general/company-management/licenses) + +11.3.0 이상에서는 유효기간이 겹치는 라이선스도 추가할 수 있으므로, 이 절차가 필요하지 않습니다. -기존 라이선스를 삭제하는 방법은 크게 두 가지가 있습니다. +11.3.0 미만 버전에서 유효기간이 겹치는 라이선스를 설치하려면, 기존 라이선스를 먼저 삭제해야 합니다. -* Docker Container 내부에서 mysql client 을 사용하여, 기존 라이선스를 삭제하기 -* QueryPie Web Console 에서 QueryPie MySQL 에 연결하여, 기존 라이선스를 삭제하기 - * QueryPie DAC 기능을 이용하는 고객의 경우, DAC 의 Database Connection 을 추가하여, QueryPie MySQL Database 에 연결할 수 있습니다. 자세한 방법은 이 문서에서 설명하지 않습니다. - -이 문서에서는 Docker Container 내부에서 mysql client 을 사용하여, 기존 라이선스를 삭제하는 방법을 설명합니다. - -#### 기존 라이선스 삭제하기 +#### 기존 라이선스 삭제 QueryPie Server Container 가 작동 중인 리눅스 서버에 터미널로 연결합니다. @@ -185,7 +184,7 @@ ubuntu@querypie:~/querypie/10.2.4$ ``` -#### QueryPie Tools 를 실행하여, License 를 설치하기 +#### QueryPie Tools를 실행하여 라이선스 설치 이제 QueryPie Tools 를 실행하여, License 를 설치합니다. 처음 설치 때와 마찬가지 방식으로, 라이선스를 설치할 수 있습니다. @@ -212,16 +211,15 @@ ubuntu@querypie:~/querypie/10.2.4$ `[License] Upload: Success` 라는 응답 메시지를 만난 경우, 정상적으로 라이선스가 설치된 것입니다. -#### QueryPie Server Container 를 재시작하기 +#### QueryPie Server Container 재시작 -이제, QueryPie Server Container 를 재시작하여 주세요. +라이선스 설치 후 QueryPie Server Container를 재시작합니다. -* `docker-compose --env-file compose-env --profile querypie down` -* `docker-compose --env-file compose-env --profile querypie up -d` - -설치된 QueryPie Web Console 에서, 제품이 정상적으로 작동하는지 확인하여 주세요. +```bash +docker-compose --env-file compose-env --profile querypie down +docker-compose --env-file compose-env --profile querypie up -d +``` -지금까지, 기존 라이선스를 교체하여, 새로운 라이선스를 설치하는 과정을 살펴보았습니다. -수고하셨습니다. +Web Console에서 제품이 정상적으로 작동하는지 확인하세요. diff --git a/src/content/ko/installation/post-installation-setup.mdx b/src/content/ko/installation/post-installation-setup.mdx index ae1e1db66..8ca5915b7 100644 --- a/src/content/ko/installation/post-installation-setup.mdx +++ b/src/content/ko/installation/post-installation-setup.mdx @@ -6,13 +6,22 @@ import { Callout } from 'nextra/components' # 설치 후 초기 설정 -운영 환경에 따라 설치 이후 필수적으로 수행이 필요한 설정들을 안내합니다. +QueryPie 설치 후 필수적으로 수행해야 하는 초기 설정을 안내합니다. -### 공통 설정 +## 설정 체크리스트 -설치 직후 QueryPie 사용 시 필요한 공통 절차 입니다. +| 순서 | 설정 항목 | 필수 여부 | +| --- | --- | --- | +| 1 | Web Base URL 설정 | 필수 | +| 2 | DAC/SAC Proxy 주소 설정 | DAC/SAC 사용 시 | +| 3 | KAC Proxy 주소 설정 | KAC 사용 시 | +| 4 | WAC Proxy 주소 설정 | WAC 사용 시 | -#### QueryPie Web Base URL 설정 +## 공통 설정 + +모든 환경에서 필수로 설정해야 하는 항목입니다. + +### QueryPie Web Base URL 설정 > 설정 경로: Admin Page → General Web Console 에 접근하기 위한 QueryPie 의 URL 주소입니다. @@ -34,9 +43,11 @@ QueryPie Web Base URL 설정 화면 -### 제품별 설정 +## 제품별 설정 + +사용하는 기능에 따라 Proxy 접속 주소를 설정합니다. -#### DAC/SAC: Proxy 접속 주소 설정 +### DAC/SAC: Proxy 접속 주소 설정 QueryPie Database 에 접속하여, DAC/SAC 의 Proxy 접속을 위한 주소를 등록합니다. @@ -79,7 +90,7 @@ DAC/SAC Proxy 접속 주소 설정 화면 -#### KAC: Proxy 접속 주소 설정 +### KAC: Proxy 접속 주소 설정 QueryPie Database 에 접속하여, KAC 의 Proxy 접속을 위한 주소를 등록합니다. @@ -102,7 +113,7 @@ KAC Proxy 접속 주소 설정 화면 -#### WAC: Proxy 접속 주소 설정 +### WAC: Proxy 접속 주소 설정 > 설정 경로: Admin Page → Web Apps → Web App Configurations WAC의 Proxy 접속 주소 설정은 Web Console 에서 수행 가능합니다. @@ -114,7 +125,7 @@ WAC의 Proxy 접속 주소 설정은 Web Console 에서 수행 가능합니다. -### 제품 설치가 완료되었습니다 +## 다음 단계 설치 후 초기 설정 과정을 진행한 것으로, QueryPie ACP 제품을 사용할 수 있는 준비가 완료되었습니다. 수고하셨습니다~! diff --git a/src/content/ko/installation/prerequisites.mdx b/src/content/ko/installation/prerequisites.mdx index 2251c4f06..11555648f 100644 --- a/src/content/ko/installation/prerequisites.mdx +++ b/src/content/ko/installation/prerequisites.mdx @@ -6,16 +6,19 @@ import { Callout } from 'nextra/components' # 설치 전 준비사항 +이 문서에서는 QueryPie ACP를 설치하기 전에 준비해야 할 사항을 안내합니다. -### 요약 +## 요약 설치를 진행하기 전에, 다음의 사항을 준비해야 합니다. -간단히 요약하면, 다음과 같습니다. -* Linux 서버 1대 -* 웹 브라우저가 설치된 PC 1대 +| 구분 | 요구사항 | +| --- | --- | +| 서버 | Linux 서버 1대 (4 vCPUs, 16 GiB Memory, 100 GiB Disk 이상) | +| 클라이언트 | 웹 브라우저가 설치된 PC 1대 | +| 네트워크 | TCP 80, 443, 9000 포트 접근 가능 | -### 서버 환경 +## 서버 환경 * Linux OS 가 설치된 서버 컴퓨터 1대 : 아래에서 `Server VM`이라고 표기합니다. * AWS, Azure, Google Cloud Platform 등의 클라우드 서비스를 이용해도 무방합니다. @@ -37,22 +40,18 @@ import { Callout } from 'nextra/components' * (선택) : 80 이 아닌 443 TLS(SSL) 포트를 사용하여 HTTPS 로 접근하려는 경우, TCP 443 포트 접근이 가능해야 합니다. -Production 환경을 위한 서버 권장 사양을 요약합니다. -* 기본 사양 : Hardware: CPU 4 vCPUs, AMD64 Architecture, Memory 16 GiB, Disk 100 GiB+ - * AWS EC2 : m6i.xlarge, m7i.xlarge, - * GCP Compute Engine : c4-standard-4, n4-standard-4 ( 또는 AMD64 아키텍처의 -standard-4 모델 ) -* 다수 이용자 운영환경의 권장 사양 : Hardware: CPU 4 또는 8 vCPUs, AMD64 Architecture, Memory 32 GiB, Disk 100 GiB+ - * AWS EC2 : m6i.2xlarge, m7i.2xlarge, r6i.xlarge - * GCP Compute Engine : c4-standard-8, n4-standard-8 ( 또는 AMD64 아키텍처의 -standard-8 모델 ) -* OS: Linux ( docker daemon 을 설치하여 사용 ) +**서버 권장 사양 요약** +* 기본 사양: 4 vCPUs (AMD64), 16 GiB Memory, 100 GiB Disk +* 다수 이용자 환경: 8 vCPUs (AMD64), 32 GiB Memory, 100 GiB Disk + +상세한 서버 사양은 [서버구성 요구사항](server-configuration-requirements)을 참조하세요. -### 리눅스 배포본 +## 리눅스 배포본 -QueryPie ACP 는 Docker, Podman 을 사용할 수 있는 대부분의 리눅스 배포본에서 정상적으로 작동합니다. -그리고, 몇가지 리눅스 배포본에서 QueryPie ACP 제품을 사용하는 경우, 기술지원을 효과적으로 제공받을 수 있습니다. +QueryPie ACP는 Docker, Podman을 사용할 수 있는 대부분의 리눅스 배포본에서 정상적으로 작동합니다. -#### 설치, 운영 과정이 검증된 리눅스 배포본 +### 설치, 운영 과정이 검증된 리눅스 배포본 * Amazon Linux 2, Amazon Linux 2023 : AWS Cloud 에서만 제공됩니다. * Ubuntu Server 22.04 LTS, 24.04 LTS @@ -61,38 +60,33 @@ QueryPie ACP 는 Docker, Podman 을 사용할 수 있는 대부분의 리눅스 여러 리눅스 배포본과 Docker, Podman 의 지원 현황에 대한 상세한 정보는 이 문서를 참조하세요: [리눅스 배포본과 Docker, Podman 지원 현황](prerequisites/linux-distribution-and-docker-podman-support-status) -### Container Engine 과 Compose Tool +## Container Engine과 Compose Tool -QueryPie 는 Container 방식으로 제공됩니다. -따라서, Container Engine 을 필수로 요구합니다. -Docker, Podman 과 같이 Image 로부터 Container 를 생성, 실행, 종료하기 위한 도구를 Container Engine 이라고 합니다. -또한, Container Engine 을 손쉽게 사용하기 위하여, Compose Tool 를 필요로 합니다. -Docker Compose 를 Compose Tool 이라고 합니다. +QueryPie는 Container 방식으로 제공되므로, Container Engine을 필수로 요구합니다. -#### Container Engine 과 버전 +### Container Engine과 버전 * Docker Desktop : 20.10 또는 이후 버전 * Docker Community Edition : 20.10 또는 이후 버전 * Docker Enterprise Edition : Docker Desktop 으로 제품의 이름이 변경되었습니다. * Podman : 4.9.0 또는 이후 버전 -#### Compose Tool 과 버전 +### Compose Tool과 버전 * Docker Compose : 2.29.0 또는 이후 버전 * Podman Compose 보다 Docker Compose 사용을 권장합니다. Podman 과 Docker Compose 조합에서 정상적으로 작동하는 것을 검증하였습니다. * Podman Compose : 1.5.0 또는 이후 버전 -### 서버의 FQDN 설정과, TLS Certificate +## 서버의 FQDN 설정과 TLS Certificate -이 항목은 필수로 요구되는 것은 아닙니다. -그러나, 보안 측면과 이용자의 사용성 측면에서, 권장하는 항목입니다. +이 항목은 필수가 아니지만, 보안과 사용성 측면에서 권장합니다. * `Server VM` 에 연결되는 Fully Qualified Domain Name (FQDN) 을 준비합니다. * `Server VM` 의 IP 주소에 연결된 DNS 설정을 적용하여, FQDN 으로 해당 호스트에 연결할 수 있는 설정을 준비합니다. * FQDN 에 해당하는 TLS 인증서 Certificate 를 준비합니다. * `https` 주소로 접근하는데 사용됩니다. -### 이용자의 PC 환경 +## 이용자의 PC 환경 * 웹 브라우저가 설치된 PC : 아래에서 `User PC`라고 표기합니다. * Chrome, Firefox, Safari, Edge 등의 최신 버전 브라우저를 사용합니다. diff --git a/src/content/ko/installation/product-versions.mdx b/src/content/ko/installation/product-versions.mdx index 50706457b..2ac6610ea 100644 --- a/src/content/ko/installation/product-versions.mdx +++ b/src/content/ko/installation/product-versions.mdx @@ -6,7 +6,7 @@ title: '제품 버전' QueryPie ACP의 공식 출시 버전 정보를 제공합니다. -### Available Versions +## Available Versions 현재 설치 및 운영이 가능한 QueryPie ACP 공식 출시 버전입니다. @@ -18,16 +18,16 @@ QueryPie ACP의 공식 출시 버전 정보를 제공합니다. | 11.3.0 | `11.3.0-559d539` | [11.3.0](../release-notes/11.3.0) | 2025. 09. 26. | Deprecated | | 11.1.2 | `11.1.2-1eaa817` | [11.1.0 ~ 11.1.2](../release-notes/11.1.0-11.1.2) | 2025. 08. 19. | Active | -#### Status +### Status * Active: 신규 설치 및 업그레이드에 사용하는 것을 권장합니다. * Deprecated: 기존 환경 유지를 목적으로 유지합니다. 신규 설치에는 권장하지 않으며, 향후 이미지 제공이 중단될 수 있습니다. -### Container Registry +## Container Registry QueryPie ACP는 다음 Container Registry를 통해 Container Image를 제공합니다. -#### Docker Hub (Recommended) +### Docker Hub (권장) Registry 위치: `docker.io/querypie` ([https://hub.docker.com/u/querypie](https://hub.docker.com/u/querypie)) @@ -38,14 +38,14 @@ Registry 위치: `docker.io/querypie` ([https://hub.docker.com/u/querypie](https * 인증 없이 사용할 수 있습니다. * `linux/amd64`, `linux/arm64`, 멀티 플랫폼 이미지를 제공합니다. -#### Harbor Registry +### Harbor Registry Registry 위치: `harbor.chequer.io/querypie` 기존 설치 및 운영 환경과의 호환성을 목적으로 제공되는 비공개 Container Registry입니다. `docker login` 명령으로 인증을 수행하여야 Container Image 를 내려받을 수 있습니다. 기술지원을 담당하는 파트너를 통하여, Container Registry 에 접근하기 위한 Username, Password 를 제공 받아야 합니다. -#### Edition Compatibility +### Edition Compatibility Community / Standard / Enterprise Edition 모두 동일한 Container Image를 사용합니다. Registry 선택에 따른 기능 차이는 없습니다. diff --git a/src/content/ko/installation/server-configuration-requirements.mdx b/src/content/ko/installation/server-configuration-requirements.mdx index 9c53f71b8..98906079c 100644 --- a/src/content/ko/installation/server-configuration-requirements.mdx +++ b/src/content/ko/installation/server-configuration-requirements.mdx @@ -4,7 +4,18 @@ title: '서버구성 요구사항' # 서버구성 요구사항 -QueryPie 를 설치, 운영하기 위한 서버의 하드웨어 성능과 처리용량에 대한 가이드를 제공합니다. -* [Public Cloud 운영서버 요구사항](server-configuration-requirements/public-cloud-production-server-requirements) -* [On-Premise VM 요구사항](server-configuration-requirements/on-premise-vm-requirements) -* [서버구성 요구사항 요약표](server-configuration-requirements/server-configuration-requirements-summary) +QueryPie를 설치하고 운영하기 위한 서버 하드웨어 성능과 처리 용량에 대한 가이드를 제공합니다. + +## 빠른 참조 + +| 구성 요소 | 기본 사양 | 권장 사양 (다수 사용자) | +| --- | --- | --- | +| QueryPie Container VM | 4 vCPUs, 15 GiB, 100 GiB Disk | 8 vCPUs, 30 GiB, 100 GiB Disk | +| QueryPie MySQL | 2 vCPUs, 16 GiB, 100 GiB Disk | 4 vCPUs, 32 GiB, 100 GiB+ Disk | +| QueryPie Redis | 2 vCPUs, 1 GiB | 2 vCPUs, 3 GiB | + +## 상세 가이드 + +* [서버구성 요구사항 요약표](server-configuration-requirements/server-configuration-requirements-summary) - 한눈에 보는 요약 +* [Public Cloud 운영서버 요구사항](server-configuration-requirements/public-cloud-production-server-requirements) - AWS, GCP, Azure +* [On-Premise VM 요구사항](server-configuration-requirements/on-premise-vm-requirements) - 물리 서버 환경 diff --git a/src/content/ko/installation/system-architecture-and-network-access-control.mdx b/src/content/ko/installation/system-architecture-and-network-access-control.mdx index 565a060e5..19ddd0274 100644 --- a/src/content/ko/installation/system-architecture-and-network-access-control.mdx +++ b/src/content/ko/installation/system-architecture-and-network-access-control.mdx @@ -4,12 +4,13 @@ title: '시스템 아키텍처와 네트워크 접근제어' # 시스템 아키텍처와 네트워크 접근제어 +QueryPie의 시스템 구성요소와 네트워크 설정에 대해 안내합니다. -### 시스템 아키텍처 +## 시스템 아키텍처 QueryPie Server, QueryPie User Agent, User PC 의 Web Browser, 그리고 이용자의 접근 대상인 Database, Linux Server 등의 시스템이 어떻게 구성되고 연결되는지 알아봅니다. -#### 시스템 아키텍처 구성도 +### 시스템 아키텍처 구성도 이 시스템 아키텍처는 단일 리눅스 서버에 QueryPie Service 를 설치하는 경우의 아키텍처입니다. TLS 인증서를 적용한 웹서비스, 고가용성을 위한 다중화 구성 등을 포함하지 않습니다. @@ -23,7 +24,7 @@ Overview of QueryPie System Architecture 각 컴포넌트에 대한 설명은 다음과 같습니다. -#### User PC 의 Web Browser +### User PC의 Web Browser 이용자의 PC 에서 웹 브라우저를 통해 QueryPie 웹 서비스에 접속합니다. QueryPie 를 이용하기 위해서는 웹 브라우저가 필수적입니다. @@ -31,7 +32,7 @@ QueryPie 관리자, 보안정책 운영자는 QueryPie Web Console 을 통해 Qu 또한, QueryPie 사용자는 QueryPie Web SQL Editor, Web Terminal 을 통해 대상 시스템에 접근할 수 있습니다. -#### User PC 의 QueryPie User Agent +### User PC의 QueryPie User Agent User PC 에서 작동하는 Database Client Application, SSH Client Application 를 이용하는 경우, QueryPie User Agent 가 필요합니다. QueryPie User Agent 는 User PC 에서 작동하는 Local Proxy Agent 의 역할을 수행합니다. @@ -40,7 +41,7 @@ QueryPie Web Console 에 로그인하면, QueryPie User Agent 를 다운로드 QueryPie User Agent 는 User PC 에서 작동하는 대부분의 Database Client Application, SSH Client Application 을 지원합니다. (이후 `3rd Party Tool` 이라고 표기합니다.) 구체적인 사례는 이 문서를 참조하세요: [Supported 3rd Party Tools (KO)](https://querypie.atlassian.net/wiki/spaces/QCP/pages/919404587) -#### QueryPie Server +### QueryPie Server Linux VM 에서 작동하는 QueryPie Server 는 Web Console, Web SQL Editor, Web Terminal 을 웹서비스로 제공합니다. 또한 SQL protocol, ssh protocol 을 이해하고 접근제어 수행하는 Proxy server 을 제공하는 핵심적 역할을 수행합니다. @@ -50,7 +51,7 @@ QueryPie Server 는 두 가지 컴포넌트를 필요로 합니다. * QueryPie Database * QueryPie Redis -#### QueryPie Database +### QueryPie Database QueryPie Database 는 QueryPie Server 의 작동을 위한 데이터를 저장합니다. QueryPie 의 User Account, Admin Account, 연결 대상 시스템의 정보, 접근제어 정책 등을 저장합니다. @@ -61,41 +62,40 @@ MySQL, MariaDB 또는 호환되는 Database 를 QueryPie Database 로 사용할 * AWS Aurora MySQL * GCP Cloud SQL for MySQL -#### QueryPie Redis +### QueryPie Redis QueryPie Redis 는 QueryPie Server 의 작동을 위한 Cache 역할을 수행합니다. QueryPie Server 가 작동하기 위해, 필수로 요구되는 컴포넌트입니다. -#### Target Database +### Target Database 이용자가 접근을 원하는 Database 서버입니다. QueryPie Server 는 이용자와 Target Database 사이의 중계 역할을 수행합니다. -#### Target Server System +### Target Server System 이용자가 접근을 원하는 Linux Server, Windows Server 등의 시스템입니다. QueryPie Server 는 이용자와 Target Server System 사이의 중계 역할을 수행합니다. -### 네트워크 접근제어 설정 +## 네트워크 접근제어 설정 -#### 네트워크 접근 유형 +### 네트워크 접근 유형 QueryPie 가 설치된 Linux VM 을 중심으로, 네트워크 연결을 Outbound, Inbound, 두 가지 유형으로 구분합니다. * Outbound : QueryPie 가 설치된 Linux VM 에서, 외부 인터넷으로 연결하는 네트워크 접근입니다. * Inbound : 이용자의 PC 또는 고객사 내부 네트워크에서, QueryPie 가 설치된 Linux VM 으로 연결하는 네트워크 접근입니다. -#### 소프트웨어 설치를 위한 네트워크 접근 +### 소프트웨어 설치를 위한 네트워크 접근 | **Access Type** | **Source** | **Destination** | **Protocol** | **Port** | **Description** | | ----------------- | --------------- | --------------------------------------------------------------------------------------------------------------------- | -------------- | ---------- | ---------------------------------------------------------------------------- | | Outbound | QueryPie Server | FQDN: `dl.querypie.com`
IPv4 Address:
`18.67.51.51`,
`18.67.51.67`,
`18.67.51.73`,
`18.67.51.76` | TCP | 443 | 제품 설치를 위한 설정파일을 내려받는 website 입니다. | | Outbound | QueryPie Server | FQDN: `harbor.querypie.io`
IPv4 Address:
`15.164.47.8`, `52.79.197.102` | TCP | 443 | 제품 설치를 위해, Docker Image 를 내려받는 website 입니다. docker 용어로는 Docker Registry 입니다. | -#### 제품 사용을 위한 네트워크 접근 +### 제품 사용을 위한 네트워크 접근 -아래의 항목은 제품 사용을 위한 네트워크 접근을 설명합니다. -QueryPie 제품의 기능에 따라, 공통, DAC, SAC, KAC, WAC 로 구분합니다. +QueryPie 제품의 기능에 따라 공통, DAC, SAC, KAC, WAC로 구분합니다. #### 공통 @@ -140,7 +140,7 @@ QueryPie 제품의 기능에 따라, 공통, DAC, SAC, KAC, WAC 로 구분합니 | ----------------- | ------------------ | ------------------------------------------------ | ---------- | -------------- | ---------- | -------------------------------- | | Inbound | All the users
| QueryPie Server
or
Network Load Balancer | Custom TCP | TCP | 7447 | From Users to QueryPie WAC Proxy | -### Load Balancers 설정 +## Load Balancers 설정 부하분산, 장애내성을 갖추기 위해, QueryPie Service 에 Load Balancer 를 적용하는 설정을 표로 설명합니다. From c92768d27f6b5b8aaac7d485ef5dbfedc21b24d9 Mon Sep 17 00:00:00 2001 From: JK Date: Fri, 6 Feb 2026 03:55:32 +0900 Subject: [PATCH 2/7] =?UTF-8?q?refactor:=20=ED=95=98=EC=9C=84=20=EB=AC=B8?= =?UTF-8?q?=EC=84=9C=20=EC=84=B9=EC=85=98=20=EC=A0=9C=EB=AA=A9=20=EC=9D=BC?= =?UTF-8?q?=EA=B4=80=EC=84=B1=20=EA=B0=9C=EC=84=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - installation-guide-setupv2sh.mdx: 특징 요약 추가, 사전 요구사항 테이블 형식화 - installation-guide-simple-configuration.mdx: setup.v2.sh 권장 안내 추가, 요구사항 정리 - comparison-of-setupsh-and-setupv2sh.mdx: 비교 요약 테이블 추가 - optimizing-dbmaxconnectionsize.mdx: 섹션 수준 조정 (### → ##) - linux-distribution-and-docker-podman-support-status.mdx: 섹션 수준 조정 - configuring-rootless-mode-with-podman.mdx: 섹션 수준 조정 - public-cloud-production-server-requirements.mdx: 섹션 수준 조정 - on-premise-vm-requirements.mdx: 구조 간소화 및 섹션 수준 조정 Co-Authored-By: Claude Opus 4.5 --- .../optimizing-dbmaxconnectionsize.mdx | 32 ++++++++--------- .../comparison-of-setupsh-and-setupv2sh.mdx | 33 +++++++++-------- .../installation-guide-setupv2sh.mdx | 36 +++++++------------ ...nstallation-guide-simple-configuration.mdx | 33 ++++++++--------- .../configuring-rootless-mode-with-podman.mdx | 10 +++--- ...ution-and-docker-podman-support-status.mdx | 26 +++++++------- .../on-premise-vm-requirements.mdx | 17 ++++----- ...c-cloud-production-server-requirements.mdx | 28 ++++++++------- 8 files changed, 104 insertions(+), 111 deletions(-) diff --git a/src/content/ko/installation/container-environment-variables/optimizing-dbmaxconnectionsize.mdx b/src/content/ko/installation/container-environment-variables/optimizing-dbmaxconnectionsize.mdx index 270e1ae42..42c69fbcb 100644 --- a/src/content/ko/installation/container-environment-variables/optimizing-dbmaxconnectionsize.mdx +++ b/src/content/ko/installation/container-environment-variables/optimizing-dbmaxconnectionsize.mdx @@ -4,11 +4,9 @@ title: 'DB_MAX_CONNECTION_SIZE 최적화' # DB_MAX_CONNECTION_SIZE 최적화 -### Overview +QueryPie MySQL 연결 설정에 사용되는 Database Connection Pool Size를 최적화하는 방법을 안내합니다. -QueryPie MySQL 연결 설정에 사용되는 Database Connection Pool Size 를 최적화하는 방법을 안내합니다. - -#### QueryPie MySQL 의 구성 +## QueryPie MySQL의 구성 QueryPie Server 는 MySQL Database 에 Meta DB, Snapshot DB, Log DB 를 구성하여 작동합니다. @@ -18,16 +16,16 @@ QueryPie Server 는 MySQL Database 에 Meta DB, Snapshot DB, Log DB 를 구성 QueryPie Server 는 Spring framework 를 사용하는 컴포넌트를 갖고 있으며, 이 컴포넌트에서는 Database Connection Pool 을 구성하여, QueryPie MySQL 에 데이터를 저장합니다. -### Database Connection Pool Size 설정하기 +## Database Connection Pool Size 설정하기 QueryPie Server Container 를 실행할 때, 환경변수를 이용하여, Database Connection Pool Size 를 설정할 수 있습니다. -#### `DB_MAX_CONNECTION_SIZE` +### `DB_MAX_CONNECTION_SIZE` Meta DB 를 위한 DB Connection Pool Size 를 지정합니다. 기본값은 20 입니다. -#### `LOG_DB_MAX_CONNECTION_SIZE` +### `LOG_DB_MAX_CONNECTION_SIZE` Log DB 를 위한 DB Connection Pool Size 를 지정합니다. 기본값은 `DB_MAX_CONNECTION_SIZE` 에 설정된 값입니다. @@ -35,13 +33,13 @@ Log DB 를 위한 DB Connection Pool Size 를 지정합니다. Snapshot DB 의 Connection Pool Size 는 이용자가 제어할 필요성이 낮아서, 이 값을 제어하기 위한 환경변수를 제공하지 않습니다. -### 일반적인 이용자 사용량, 부하 발생의 경우 +## 일반적인 이용자 사용량, 부하 발생의 경우 `DB_MAX_CONNECTION_SIZE` 의 기본값 20 을 그대로 사용하는 것을 권장합니다. 일반적인 경우에 두루 사용할 수 있는 Connection Pool Size 의 크기입니다. PoC 환경 뿐만 아니라, 일반적인 Production 환경에서 충분히 처리성능을 낼 수 있는 수치를 기본값으로 권장하고 있습니다. -### 많은 사용량, 높은 부하 발생의 경우 +## 많은 사용량, 높은 부하 발생의 경우 `DB_MAX_CONNECTION_SIZE` 의 값을 20~40 사이의 값으로 설정하는 것을 권장합니다. 적정한 범위 내에서 `DB_MAX_CONNECTION_SIZE` 가 높아지면, QueryPie 가 동시에 처리 가능한 부하의 양이 늘어납니다. @@ -50,7 +48,7 @@ DB 서버의 처리성능이 높고, CPU 수가 많은 경우, `DB_MAX_CONNECTIO Server Container 가 작동하는 Linux VM 의 처리성능이 높고, CPU 수가 많은 경우, `DB_MAX_CONNECTION_SIZE` 를 높입니다. Server Container 의 수가 늘어나면, `DB_MAX_CONNECTION_SIZE` 를 낮춥니다. -### `DB_MAX_CONNECTION_SIZE`설정값 요약표 +## `DB_MAX_CONNECTION_SIZE` 설정값 요약표 | **DB_MAX_CONNECTION_SIZE** | **Description** | | ---------------------------- | -------------------------------------------------------------------------------- | @@ -60,12 +58,12 @@ Server Container 의 수가 늘어나면, `DB_MAX_CONNECTION_SIZE` 를 낮춥니 | 10 | 운영 환경에서, MySQL 연결수를 줄이고자 하는 경우에 적합합니다. | | 5 | PoC 에서 기능 테스트를 수행하는 경우, 운영 환경에서 사용자 수가 적은 경우에 적합합니다. | -### `DB_MAX_CONNECTION_SIZE`와 하드웨어 용량의 관계식 +## `DB_MAX_CONNECTION_SIZE`와 하드웨어 용량의 관계식 개발팀 내부의 성능 최적화 테스트를 통해, `DB_MAX_CONNECTION_SIZE` 과 QueryPie Server VM, DB 의 하드웨어 처리용량 사이에 다음의 관계식이 있다는 것을 도출하였습니다. 이 관계식을 참조하여, `DB_MAX_CONNECTION_SIZE` 값을 설정하면, 최적의 처리성능을 얻는 동시에, 가능한 작은 `DB_MAX_CONNECTION_SIZE` 값을 설정할 수 있습니다. -#### QueryPie MySQL 을 분리구성하는 경우 +### QueryPie MySQL을 분리 구성하는 경우 하나의 Linux VM 내에 QueryPie Server Container 와 QueryPie MySQL 을 함께 실행하지 않고, 별도의 VM 또는 Cloud Service 를 이용해, 분리된 MySQL Instance 를 구성하는 경우입니다. Production 환경에 적용하는 것을 권장합니다. @@ -96,7 +94,7 @@ minimum ( Application_CPU_Count / Application_Node_Count, RDS_CPU_Count ) * 10 = 27 ``` -#### 단일 Linux VM 구성의 경우 +### 단일 Linux VM 구성의 경우 하나의 Linux VM 에 QueryPie Server Container, QueryPie MySQL 을 함께 실행하는 경우입니다. PoC 환경에 사용하는 것이 적합합니다. @@ -114,13 +112,13 @@ Application_CPU_Count * 2.5 ``` -### QueryPie MySQL 설정에서 충분한 연결수를 허용하기 +## QueryPie MySQL 설정에서 충분한 연결수 허용하기 QueryPie Server 는 Connection Pool 을 이용하여 QueryPie MySQL 에 연결을 맺습니다. 만일, MySQL Database Server 가 충분한 연결수를 허용하지 않는 경우, QueryPie Server 가 MySQL 에 연결을 생성하지 못하고, 오작동하는 현상이 발생하게 됩니다. 이 문제 현상은 QueryPie MySQL 가 허용하는 연결수보다, QueryPie Server 가 요구하는 DB 연결수가 더 큰 경우에 발생합니다. -#### DB 연결을 생성하지 못하는 현상 +### DB 연결을 생성하지 못하는 현상 Web Console 에서, `[API] Could not open JPA EntityManager for transaction` 라는 에러 메시지를 만나게 됩니다. @@ -132,7 +130,7 @@ Web Console 에서, `[API] Could not open JPA EntityManager for transaction` 라 -#### 문제해결방법 1) QueryPie MySQL 이 허용하는 연결수를 늘이기 +### 해결방법 1: QueryPie MySQL이 허용하는 연결수 늘이기 두 가지 설정값을 500 이상으로 늘이는 설정을 적용할 수 있습니다. 이를 통해, QueryPie Server 가 요구하는 DB 연결수보다, QueryPie MySQL 가 허용하는 연결수를 더 크게 설정할 수 있습니다. @@ -143,7 +141,7 @@ Web Console 에서, `[API] Could not open JPA EntityManager for transaction` 라 * max_connections * [https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_max_connections](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_max_connections) -#### 문제해결방법 2) DB_MAX_CONNECTION_SIZE 를 줄이기 +### 해결방법 2: DB_MAX_CONNECTION_SIZE 줄이기 QueryPie 이용자 수가 적고, 이용량 부하가 낮은 경우, `DB_MAX_CONNECTION_SIZE` 설정값을 줄일 수 있습니다. 이를 통해, QueryPie MySQL 가 허용하는 연결수보다, QueryPie Server 가 요구하는 DB 연결수를 더 작게 설정할 수 있습니다. diff --git a/src/content/ko/installation/installation/comparison-of-setupsh-and-setupv2sh.mdx b/src/content/ko/installation/installation/comparison-of-setupsh-and-setupv2sh.mdx index eb3713846..b0e95187e 100644 --- a/src/content/ko/installation/installation/comparison-of-setupsh-and-setupv2sh.mdx +++ b/src/content/ko/installation/installation/comparison-of-setupsh-and-setupv2sh.mdx @@ -4,23 +4,28 @@ title: 'setup.sh, setup.v2.sh 비교' # setup.sh, setup.v2.sh 비교 -### 들어가기 +두 설치 프로그램의 작동 방식, 특징과 차이점을 비교합니다. -2025년 8월 현재, setup.sh 는 파트너를 위해 제공된 QueryPie 설치 프로그램입니다. -setup.v2.sh 는 QueryPie Community Edition 출시와 함께 제공되는 QueryPie 설치 프로그램입니다. +## 요약 -이 두 가지 설치 프로그램의 작동 방식, 특징과 차이점을 이 문서에서 살펴봅니다. +| 구분 | setup.sh | setup.v2.sh | +| --- | --- | --- | +| 대상 | 파트너, 기존 고객 | 신규 고객, Community Edition | +| 자동화 수준 | 낮음 (수동 설정 필요) | 높음 (전체 과정 자동화) | +| Container Registry | Harbor (계정 필요) | Docker Hub (인증 불필요) | +| Rootless Mode | 추가 설정 필요 | 기본 지원 | +| 구버전 지원 | Version 10 이전 지원 | Version 11 이상만 지원 | -### 설치 프로그램의 기능 범위 +## 설치 프로그램의 기능 범위 -#### setup.sh 의 설치 기능 +### setup.sh의 설치 기능 * Container Engine, Compose Tool 이 발견되지 않은 경우, 이를 설치합니다. * Container Engine : Docker * Compose Tool : Docker Compose * `./querypie/version` 경로에 Compose 를 위한 package.tar.gz 을 설치합니다. -#### setup.v2.sh 의 설치 기능 +### setup.v2.sh의 설치 기능 * Container Engine, Compose Tool 이 발견되지 않은 경우, 이를 설치합니다. * Container Engine : Docker 또는 Podman @@ -32,7 +37,7 @@ setup.v2.sh 는 QueryPie Community Edition 출시와 함께 제공되는 QueryPi * QueryPie MySQL 의 Migration 을 수행하고, QueryPie App Container 를 실행합니다. * `./querypie/current` 라는 Symbolic Link 를 `./querypie/` 으로 연결하여, 현재 작동 중인 버전을 명시합니다. -#### setup.v2.sh 의 업그레이드, 삭제 등 추가 기능 +### setup.v2.sh의 업그레이드, 삭제 등 추가 기능 setup.v2.sh 는 제품의 설치 외에도 다른 주요 기능을 제공합니다. @@ -42,7 +47,7 @@ setup.v2.sh 는 제품의 설치 외에도 다른 주요 기능을 제공합니 * setup.sh 와 동등하게, Compose Package 설치까지만 수행하는 모드를 제공합니다. * 검토 중 환경변수 설정파일 `.env` 의 설정값을 이용자 확인, 입력을 거쳐 채웁니다. -### Compose 설정과 환경설정의 차이 +## Compose 설정과 환경설정의 차이 | **Topic** | **setup.sh** | **setup.v2.sh** | | ----------------- | ---------------------------------------------------------- | -------------------------------------------------- | @@ -53,7 +58,7 @@ setup.v2.sh 는 제품의 설치 외에도 다른 주요 기능을 제공합니 | Application Log | `/var/log/querypie/` - 10.2.x
`./querypie/log/` - 11.x | `./querypie/log/` | | 작동 중 버전의 Symlink | (없음) | `./querypie/current` | -### MySQL Data Dir 의 위치 변경 +## MySQL Data Dir의 위치 변경 MySQL Data Dir 의 경로가 변경되면서, 다음의 장점이 생깁니다. @@ -66,13 +71,13 @@ MySQL Data Dir 의 경로가 변경되면서, 다음의 장점이 생깁니다. * setup.sh 로 제품을 이미 설치한 서버에, setup.v2.sh 를 이용해 새로운 버전을 설치할 수 있습니다. 그러나, MySQL Data Dir 변경에 따라, **기존 데이터가 자동으로 이관되지 않습니다** . 새로운 설치, 업그레이드 등 목적에 따라, MySQL Data 디렉토리를 설치 담당자가 적절히 이동하여야 합니다. -### Rootless Mode 지원 +## Rootless Mode 지원 setup.sh 로 설치하는 경우, Rootless Mode 의 Docker 환경에서 실행하기 위해, 추가적인 설정 변경이 필요합니다. setup.v2.sh 로 설치하는 경우, Rootless Mode 의 Docker, Podman 환경에서 실행하기 위해, 추가적인 설정 변경이 필요하지 않습니다. -#### setup.v2.sh - Rootless Mode 설정 방법 +### setup.v2.sh - Rootless Mode 설정 방법 Rootless Mode 로 Container Engine 을 실행하도록 먼저 환경을 구성합니다. setup.v2.sh 를 이용하여 Podman 을 설치하는 경우, 기본적으로 Rootless Mode 환경이 적용됩니다. @@ -81,7 +86,7 @@ Docker 를 사용하는 경우, 별도의 문서를 참조하여, Rootless Mode 이후, `setup.v2.sh` 를 실행할 때, `--universal` 옵션을 추가하여, QueryPie 를 설치하면, Rootless Mode 에 적합한 Compose package.tar.gz 이 설치됩니다. -### setup.v2.sh 문제현상, 오류 신고하기 +## setup.v2.sh 문제 신고 setup.v2.sh 는 실행 초기에, 스크립트 버전, 환경 정보를 콘솔에 출력합니다. @@ -90,7 +95,7 @@ setup.v2.sh 와 관련된 문제 현상을 신고할 때에는, 다음의 두 * setup.v2.sh 실행시 옵션을 포함한 명령줄, 스크립트 버전을 포함한 콘솔 로그 앞부분 5줄 * 문제 현상이 발생한 마지막 콘솔 로그 5줄 또는 관련 내용 -#### 스크립트 버전을 포함한 콘솔 로그의 예시 +### 스크립트 버전을 포함한 콘솔 로그 예시 ``` jk@host ~ % ./setup.v2.sh --universal diff --git a/src/content/ko/installation/installation/installation-guide-setupv2sh.mdx b/src/content/ko/installation/installation/installation-guide-setupv2sh.mdx index 4f9cf0539..8ae7846e1 100644 --- a/src/content/ko/installation/installation/installation-guide-setupv2sh.mdx +++ b/src/content/ko/installation/installation/installation-guide-setupv2sh.mdx @@ -6,36 +6,26 @@ import { Callout } from 'nextra/components' # 설치 가이드 - setup.v2.sh - -## 소개 - -이 설치 가이드는 하나의 서버 컴퓨터에 QueryPie 서버를 설치하는 간단한 구성의 설치 방법을 안내합니다. -간단한 구성으로 설치하더라도, 대부분의 쿼리파이 기능을 시험해 볼 수 있습니다. - -이 가이드에서 안내하는 setup.v2.sh 설치 프로그램은 기존의 설치 과정을 자동으로 수행합니다. -자동화된 설치 과정은 기존의 설치 과정과 주요 부분이 동일합니다. -기존 설치 과정은 이 문서를 참조하세요: [설치 가이드 - 간단한 구성](installation-guide-simple-configuration) - -이 설치 방식은 실제 운영 환경에서 사용하기에는 적합하지 않습니다. -실제 운영 환경에 사용하기에 적합한 설치 방법은 별도로 제공되는 [QueryPie Installation Guide]를 참고하십시오. +setup.v2.sh를 사용하여 QueryPie를 자동으로 설치하는 방법을 안내합니다. -QueryPie 10.3.0 또는 이후 버전을 대상으로 하는 PoC 용도의 설치 가이드입니다. +**setup.v2.sh 특징** +* 설치 과정 자동화 (컨테이너 엔진, 환경설정, 이미지 다운로드, 실행) +* Docker Hub 공개 이미지 사용 (별도 계정 불필요) +* Podman + Rootless Mode 지원 +* macOS (Apple Silicon) 지원 -## 설치 전 준비사항 - -설치를 진행하기 전에, 다음의 사항을 준비해야 합니다. -간단히 요약하면, 다음과 같습니다. - -* Linux 서버 1대 -* 웹 브라우저가 설치된 PC 1대 +## 사전 요구사항 -자세한 것은 다음 문서를 참조하세요: [설치 전 준비사항](../prerequisites) +| 구분 | 요구사항 | +| --- | --- | +| 서버 | Linux 서버 1대 (4 vCPUs, 16 GiB Memory, 100 GiB Disk) | +| 클라이언트 | 웹 브라우저가 설치된 PC 1대 | -## 시스템 아키텍처 +상세한 요구사항: [설치 전 준비사항](../prerequisites) -다음 문서를 참조하세요: [시스템 아키텍처와 네트워크 접근제어](../system-architecture-and-network-access-control) +시스템 구성: [시스템 아키텍처와 네트워크 접근제어](../system-architecture-and-network-access-control) ## 설치 과정 diff --git a/src/content/ko/installation/installation/installation-guide-simple-configuration.mdx b/src/content/ko/installation/installation/installation-guide-simple-configuration.mdx index 48dd47a47..3193ea154 100644 --- a/src/content/ko/installation/installation/installation-guide-simple-configuration.mdx +++ b/src/content/ko/installation/installation/installation-guide-simple-configuration.mdx @@ -6,32 +6,29 @@ import { Callout } from 'nextra/components' # 설치 가이드 - 간단한 구성 +setup.sh를 사용하여 QueryPie를 수동으로 설치하는 방법을 안내합니다. -## 소개 - -이 설치 가이드는 하나의 서버 컴퓨터에 QueryPie ACP 서버를 설치하는 간단한 구성의 설치 방법을 안내합니다. -간단한 구성으로 설치하더라도, 대부분의 쿼리파이 기능을 시험해 볼 수 있습니다. - -그러나, 이 설치 방식은 실제 운영 환경에서 사용하기에는 적합하지 않습니다. -실제 운영 환경에 사용하기에 적합한 설치 방법은 별도로 제공되는 [QueryPie Installation Guide]를 참고하십시오. + +**신규 설치에는 setup.v2.sh 사용을 권장합니다.** +이 가이드는 기존 고객과 파트너를 위한 설치 방법입니다. +신규 설치는 [설치 가이드 - setup.v2.sh](installation-guide-setupv2sh)를 참조하세요. + -QueryPie 10.3.0 또는 이후 버전을 대상으로 하는 PoC 용도의 설치 가이드입니다. +이 가이드는 QueryPie 10.3.0 이상, PoC 용도의 단일 서버 구성에 적합합니다. -## 설치 전 준비사항 - -설치를 진행하기 전에, 다음의 사항을 준비해야 합니다. -간단히 요약하면, 다음과 같습니다. - -* Linux 서버 1대 -* 웹 브라우저가 설치된 PC 1대 +## 사전 요구사항 -자세한 것은 다음 문서를 참조하세요: [설치 전 준비사항](../prerequisites) +| 구분 | 요구사항 | +| --- | --- | +| 서버 | Linux 서버 1대 (4 vCPUs, 16 GiB Memory, 100 GiB Disk) | +| 클라이언트 | 웹 브라우저가 설치된 PC 1대 | +| Container Registry | Harbor 계정 (Username, Password) | -## 시스템 아키텍처 +상세한 요구사항: [설치 전 준비사항](../prerequisites) -다음 문서를 참조하세요: [시스템 아키텍처와 네트워크 접근제어](../system-architecture-and-network-access-control) +시스템 구성: [시스템 아키텍처와 네트워크 접근제어](../system-architecture-and-network-access-control) ## 설치 과정 diff --git a/src/content/ko/installation/prerequisites/configuring-rootless-mode-with-podman.mdx b/src/content/ko/installation/prerequisites/configuring-rootless-mode-with-podman.mdx index 604509658..ed3884925 100644 --- a/src/content/ko/installation/prerequisites/configuring-rootless-mode-with-podman.mdx +++ b/src/content/ko/installation/prerequisites/configuring-rootless-mode-with-podman.mdx @@ -9,7 +9,7 @@ QueryPie 는 Docker 와 Podman, 두 컨테이너 엔진 환경을 모두 지원 Podman 은 기본적인 설치 구성에서 Rootless Mode 로 작동합니다. 이에 따라, 고객사의 보안정책에 따라 Rootless Mode 환경을 구성해야 경우, Podman 으로 구현하는 것을 권장합니다. -### Podman 을 간편하게 설치하기 +## Podman을 간편하게 설치하기 setup.v2.sh 를 이용하면, Podman 을 간편하게 설치할 수 있습니다. setup.v2.sh 가 자동으로 설치하는 Podman 은 Rootless Mode 를 기본으로 적용합니다. @@ -32,7 +32,7 @@ Podman 을 설치하지 않고, Docker 를 설치하여 주는 리눅스 배포 * Amazon Linux 2, Amazon Linux 2023 * Ubuntu 22.04 LTS -### Rootless Mode Podman 을 수작업으로 설치하기 +## Rootless Mode Podman을 수작업으로 설치하기 Red Hat Enterprise Linux, Rocky 에서는 다음 명령으로 Podman 을 수작업으로 직접 설치할 수 있습니다. ```bash @@ -51,7 +51,7 @@ $ sudo apt-get -y -qq install podman podman-docker $ systemctl --user enable --now podman.socket ``` -### Rootless Mode Podman 에서 QueryPie 설치하기 +## Rootless Mode Podman에서 QueryPie 설치하기 setup.v2.sh 를 이용하면, Rootless Mode Podman 환경에서 QueryPie 를 간편하게 설치할 수 있습니다. @@ -68,7 +68,7 @@ $ bash <(curl -s https://dl.querypie.com/setup.v2.sh) --install 11.0.1 위의 명령을 실행하면, Compose 를 위한 package.tar.gz 설정, `.env` 환경변수 설정, Container 이미지 내려받기, Migration 실행하기, Container 실행하기, Rootless Mode Podman 을 위한 systemd service 등록 등 전체 설치 과정이 자동으로 수행됩니다. -#### 리눅스 서버 재시작과 systemd service 등록 +### 리눅스 서버 재시작과 systemd service 등록 Rootless Mode Podman 의 경우, 리눅스 서버가 재시작하는 경우, 추가적인 설정을 하지 않으면, Container 가 자동으로 실행되지 않습니다. 이는 Rootless Mode Podman 의 특성입니다. @@ -117,7 +117,7 @@ $ systemctl --user disable podman-querypie-database.service QueryPie 를 원활히 운영하려면, `systemctl` 명령을 이용하여 systemd service 를 관리하는 방법에 익숙하여야 합니다. 그러나, 이 문서에서는 `systemctl` 명령을 이용하여 systemd service 를 관리하는 방법을 상세히 다루지 않습니다. -### 참고자료 +## 참고자료 * Red Hat Enterprise Linux, Rootless Podman 환경에서 systemd service 를 이용해 container 를 자동으로 실행하기 * [https://www.redhat.com/en/blog/container-systemd-persist-reboot](https://www.redhat.com/en/blog/container-systemd-persist-reboot) diff --git a/src/content/ko/installation/prerequisites/linux-distribution-and-docker-podman-support-status.mdx b/src/content/ko/installation/prerequisites/linux-distribution-and-docker-podman-support-status.mdx index 51f9719ea..394f00a21 100644 --- a/src/content/ko/installation/prerequisites/linux-distribution-and-docker-podman-support-status.mdx +++ b/src/content/ko/installation/prerequisites/linux-distribution-and-docker-podman-support-status.mdx @@ -15,7 +15,7 @@ QueryPie Server는 Docker와 Podman 컨테이너 엔진에서 검증되었으며 * 최종 업데이트: 2025년 08월 29일 * 검증 기준일: 2025년 08월 29일 -### 컨테이너 엔진과 Compose +## 컨테이너 엔진과 Compose QueryPie Server는 컨테이너 기반으로 배포·운영되며, Docker와 Podman 두 컨테이너 엔진에서 기능 검증을 완료하고 기술지원을 제공합니다. @@ -28,7 +28,7 @@ Compose 의 구현체로 Docker Compose 가 널리 사용되며, Docker, Podman, Docker Compose 는 하나의 실행파일로 구성되어 있고, 다른 패키지에 의존성이 없어, 설치가 간편합니다. Podman 의 경우, Python 으로 구현된 Podman Compose 라는 구현체가 제공되기도 합니다. -#### 권장하는 컨테이너 엔진과 Compose 구성 +### 권장하는 컨테이너 엔진과 Compose 구성 QueryPie는 운영 환경에서 **Docker + Docker Compose** 조합 또는 **Podman + Docker Compose** 조합을 1차 권장합니다. 권장 최소 버전은 Docker Engine 23.0 (23년 2월 출시) 이상, Docker Compose 2.29.0 (24년 7월 출시) 이상, Podman 4.9.0 (24년 1월 출시) 이상으로 검증되어 있습니다. @@ -41,7 +41,7 @@ Podman + Podman Compose 조합은 기술적으로 지원되나, Python 의존성 특히, 많이 사용되는 Amazon Linux 2023 에서 Podman 을 지원하지 않는다는 것, 25년 출시된 Red Hat Enterprise Linux 10 에서 Docker 를 지원하지 않는다는 것에 유의하여 주세요. -### 리눅스 배포본의 현황 요약표 +## 리눅스 배포본의 현황 요약표 아래 표는 QueryPie 에서 공식적으로 기술지원을 제공하는 배포판과 Docker, Podman 지원 현황을 정리한 것입니다. Docker, Podman 지원 현황은 QueryPie 를 실행, 관리하기 위한 버전을 제공되는지 여부를 기준으로 합니다. @@ -220,11 +220,11 @@ RHEL 9 바이너리 호환 -### 리눅스 배포본의 특징 +## 리눅스 배포본의 특징 QueryPie 팀에서 기술지원을 제공하는 리눅스 배포본의 현황을 설명합니다. -#### Amazon Linux 2 (2018년 6월 출시) +### Amazon Linux 2 (2018년 6월 출시) Amazon Linux 2는 RHEL 7 계열을 기반으로 AWS가 EC2에 최적화하여 제공하는 배포판으로, 장기간의 안정적 운영을 위해 널리 사용되어왔습니다. AWS의 공식 지원 정책에 따르면 Amazon Linux 2의 공식 보안·버그 패치 제공은 2026-06-30까지로 예정되어 있어(출처: [Amazon Linux 2 FAQs](https://aws.amazon.com/amazon-linux-2/faqs/)), 새로운 신규 서버 구축이나 장기 운영을 계획 중이라면 수명 주기가 더 긴 Amazon Linux 2023 또는 Ubuntu/RHEL 계열로의 이전을 검토하시기 바랍니다. @@ -236,7 +236,7 @@ Compose는 Docker Compose 플러그인(v2)을 함께 배포·업데이트할 수 * Docker, Docker Compose 조합을 사용하기에 적합합니다. * **Podman 은 지원되지 않습니다** . -#### Amazon Linux 2023 (2023년 3월 출시) +### Amazon Linux 2023 (2023년 3월 출시) Amazon Linux 2023(AL2023)은 Fedora를 상류(upstream)로 채택해 주기적 릴리스, 지원 일정을 명확히 한 차세대 AWS 리눅스입니다. GA는 2023년 3월에 이뤄졌고, 표준 지원(Standard Support)은 2027년 6월 30일, 유지보수 지원(Maintenance Support)은 2029년 6월 30일까지 제공되는 5년 지원 모델을 따릅니다(출처: [Amazon Linux 2023 FAQs](https://aws.amazon.com/linux/amazon-linux-2023/faqs/)). @@ -248,7 +248,7 @@ AWS가 제공하는 설치 가이드에서도 Docker 중심의 운영 모델이 * Docker, Docker Compose 조합을 사용하기에 적합합니다. Amazon Linux 2023 의 dnf 패키지를 설치하는 경우, **Docker 25.0.8** 버전이 기본 설치됩니다. * **Podman 은 지원되지 않습니다.** Amazon Linux 2023 은 Podman 설치가 어렵고, 검증된 설치 패키지가 제공되지 않습니다. 상당수 이용자가 Podman 을 배포본에 추가하기를 요청하였으나, AWS 에서 이를 완곡히 거절하고, Podman 에 대한 기술지원을 하지 않는 것으로 보입니다. -#### Red Hat Enterprise Linux 8 (2019년 5월 출시) +### Red Hat Enterprise Linux 8 (2019년 5월 출시) RHEL 8은 2019년 5월 7일 공개되었고, Full Support는 2024년 5월 31일에 종료되었으며, Maintenance Support는 2029년 5월 31일까지, 선택 시 Extended Life Cycle Support(ELS)는 2032년 5월 31일까지 이어집니다. 기업 현장에서 가장 널리 배포된 EL8 생태계의 중심으로, Red Hat은 Docker 엔진 대신 Podman을 기본 컨테이너 엔진으로 제공합니다. @@ -260,7 +260,7 @@ Compose 측면에서는 Docker Compose(v2 플러그인)를 Docker 엔진과 함 * Docker, Docker Compose 조합을 사용하기에 적합합니다. **Docker 최신 버전의 패키지가 제공** 됩니다. 25년 8월 현재 **28.3.3** 버전이 제공됩니다. * [https://docs.docker.com/engine/install/rhel/](https://docs.docker.com/engine/install/rhel/) -#### Red Hat Enterprise Linux 9 (2022년 5월 출시) +### Red Hat Enterprise Linux 9 (2022년 5월 출시) RHEL 9는 2022년 5월 18일 릴리스되었고, Full Support는 2027년 5월 31일, Maintenance Support는 2032년 5월 31일, 선택 ELS는 2035년 5월 31일까지 제공됩니다. 운영 모델은 RHEL 8과 동일하게 Podman 중심이며, 루트리스 모드와 시스템 통합(systemd 유저 서비스 등)에서 성숙도가 높아졌습니다. @@ -271,7 +271,7 @@ Docker CE는 공식 RHEL 리포지터리의 지원 범위 밖이지만, Docker * Docker, Docker Compose 조합을 사용하기에 적합합니다. **Docker 최신 버전의 패키지가 제공** 됩니다. 25년 8월 현재 **28.3.3** 버전이 제공됩니다. * [https://docs.docker.com/engine/install/rhel/](https://docs.docker.com/engine/install/rhel/) -#### Red Hat Enterprise Linux 10 (2025년 5월 출시) +### Red Hat Enterprise Linux 10 (2025년 5월 출시) RHEL 10은 2025년 5월 20일에 공개되었으며, Red Hat의 표준 정책에 따라 Full Support는 2030년 5월 31일, Maintenance Support는 2035년 5월 31일, 선택 ELS는 2038년 5월 31일까지 이어지는 로드맵을 가집니다. RHEL 10에서는 Docker 엔진과 docker 명령이 기본 제공에서 제거되었고, Red Hat의 공식 지원도 Podman에 한정됩니다. @@ -281,7 +281,7 @@ Docker를 외부 업스트림에서 설치하는 것은 기술적으로 가능 * Podman, Docker Compose 조합을 사용하기에 적합합니다. **Podman 5.4.0** 버전이 설치됩니다. * **Docker 패키지가 제공되지 않습니다** . (2025년 8월 현재) CentOS Stream 10 에서 Docker 패키지가 준비되어 있으나, 설치하여 실행할 때, 오류가 발생합니다. -#### Ubuntu 22.04 LTS Jammy Jellyfish +### Ubuntu 22.04 LTS Jammy Jellyfish Ubuntu 22.04 LTS는 2022년 4월 21일 공개되었고, 표준 지원은 2027년 4월까지, Extended Security Maintenance(ESM)는 2032년 4월까지 제공됩니다. Canonical은 서버·클라우드 환경에서 Docker와 Podman 모두를 공식 문서·저장소를 통해 제공하며, Docker는 Docker 공식 APT 리포지터리 또는 Ubuntu의 docker.io/플러그인 패키지로, Podman은 배포본 기본 저장소에서 설치할 수 있습니다. @@ -292,7 +292,7 @@ Ubuntu 특유의 폭넓은 커뮤니티 생태계와 빠른 보안 패치 제공 * Docker, Docker Compose 조합을 사용하기에 적합합니다. **Docker 최신 버전의 패키지가 제공** 됩니다. 25년 8월 현재 **28.3.3** 버전이 제공됩니다. * [https://docs.docker.com/engine/install/ubuntu/](https://docs.docker.com/engine/install/ubuntu/) -#### Ubuntu 24.04 LTS Noble Numbat +### Ubuntu 24.04 LTS Noble Numbat Ubuntu 24.04 LTS는 2024년 4월 25일 공개되었으며, 표준 지원은 2029년 4월까지, ESM은 2036년 4월까지 이어집니다. 최신 LTS답게 컨테이너 관련 툴체인의 버전이 상향되어 있으며, Docker는 Docker 공식 리포지터리와 Canonical 패키지 모두에서 최신 Compose 플러그인과 함께 배치할 수 있습니다. @@ -303,7 +303,7 @@ Podman 역시 기본 저장소에서 제공되어 루트리스 실행과 사용 * Docker, Docker Compose 조합을 사용하기에 적합합니다. **Docker 최신 버전의 패키지가 제공** 됩니다. 25년 8월 현재 **28.3.3** 버전이 제공됩니다. * [https://docs.docker.com/engine/install/ubuntu/](https://docs.docker.com/engine/install/ubuntu/) -#### Rocky Linux 9 (2022년 7월 출시) +### Rocky Linux 9 (2022년 7월 출시) Rocky Linux 9 역시 RHEL 9과 동형의 릴리스 정책을 따르며, 유지보수 지원은 2032년 5월 31일까지 제공됩니다. 기본 컨테이너 스택은 Podman이며, 루트리스 실행과 cgroup, systemd 연계가 성숙해 복잡한 다중 컨테이너 서비스를 운영하기 용이합니다. @@ -314,7 +314,7 @@ QueryPie Server는 두 엔진 모두에서 동등한 품질로 동작하도록 * Docker, Docker Compose 조합을 사용하기에 적합합니다. **Docker 최신 버전의 패키지가 제공** 됩니다. 25년 8월 현재 **28.3.3** 버전이 제공됩니다. * [https://docs.docker.com/engine/install/rhel/](https://docs.docker.com/engine/install/rhel/) -#### CentOS Stream (2021년 이후) +### CentOS Stream (2021년 이후) 기존 CentOS 의 대체 배포판으로, RHEL 의 차기 릴리스를 미리 반영하는 롤링 업데이트 방식을 채택하고 있습니다. 안정성 면에서 RHEL 및 Amazon Linux 대비 변동성이 있으므로, 장기 운영보다는 개발 및 테스트 환경에 적합합니다. diff --git a/src/content/ko/installation/server-configuration-requirements/on-premise-vm-requirements.mdx b/src/content/ko/installation/server-configuration-requirements/on-premise-vm-requirements.mdx index 5705a8cbd..45900d8a0 100644 --- a/src/content/ko/installation/server-configuration-requirements/on-premise-vm-requirements.mdx +++ b/src/content/ko/installation/server-configuration-requirements/on-premise-vm-requirements.mdx @@ -4,16 +4,17 @@ title: 'On-Premise VM 요구사항' # On-Premise VM 요구사항 -### 개요 +On-Premise 물리서버의 Virtual Machine에서 QueryPie를 운영하기 위한 가이드입니다. -On-Premise 물리서버에서 작동하는 Virtual Machine 위에서, QueryPie Server Container 를 운영하는 경우에 대한 지침을 제공합니다. -Production 환경의 운영을 위해, 다음과 같은 구성을 적용하는 것을 권장합니다. +## 개요 + +Production 환경의 운영을 위해 다음과 같은 구성을 권장합니다. * High Availability 구성 적용 -* L7 Load Balancer, L4 Load Balancer 를 적용하여, 고가용성, 부하분산에 적합한 구성을 적용합니다. -* 2개 이상의 VM Instance 를 Load Balancer 의 Upstream 서버로 둡니다. 요구되는 처리용량이 높은 경우, VM Instance 의 수를 늘이는 Scale-Out 방식의 구성을 적용합니다. +* L7/L4 Load Balancer를 적용하여 고가용성, 부하분산 구성 +* 2개 이상의 VM Instance를 Upstream 서버로 구성 (Scale-Out 방식) -### QueryPie Container 용 VM 모델 +## QueryPie Container용 VM 모델 기본사양 : CPU 4 vCPUs AMD64 Architecture, Memory 15 GiB 이상, Disk 100 GiB, CPU AMD @@ -23,13 +24,13 @@ Production 환경의 운영을 위해, 다음과 같은 구성을 적용하는 * 권장사양의 VM 을 두 개 이상 생성하여, Scale-Out 구성을 적용하는 것을 권장합니다. -### QueryPie MySQL 용 VM 모델 +## QueryPie MySQL용 VM 모델 기본사양 : CPU 2 vCPUs, Memory 8 GiB 이상, Disk 100 GiB 이상 높은 처리량이 필요한 경우 권장사양 : CPU 8 vCPUs, Memory 32 GiB 이상, Disk 100 GiB 이상 ( **저장용량 크기는 별도 산정 필요** ) -### QueryPie Redis 용 VM 모델 +## QueryPie Redis용 VM 모델 기본사양 : CPU 2 vCPUs, Memory 1 GiB 이상 diff --git a/src/content/ko/installation/server-configuration-requirements/public-cloud-production-server-requirements.mdx b/src/content/ko/installation/server-configuration-requirements/public-cloud-production-server-requirements.mdx index 574ea6018..e2dc532ab 100644 --- a/src/content/ko/installation/server-configuration-requirements/public-cloud-production-server-requirements.mdx +++ b/src/content/ko/installation/server-configuration-requirements/public-cloud-production-server-requirements.mdx @@ -4,9 +4,11 @@ title: 'Public Cloud 운영서버 요구사항' # Public Cloud 운영서버 요구사항 -### 개요 +AWS, GCP, Azure 등 Public Cloud에서 QueryPie를 운영하기 위한 서버 구성 가이드입니다. -QueryPie 서버를 AWS, GCP, Azure 등 Public Cloud 에서 운영하는 경우, 다음과 같은 구성을 적용하는 것을 권장합니다. +## 개요 + +Public Cloud에서는 다음과 같은 구성을 권장합니다. * High Availability 구성 적용 * Application Load Balancer, Network Load Balancer 를 적용하여, 고가용성, 부하분산에 적합한 구성을 적용합니다. @@ -17,7 +19,7 @@ QueryPie 서버를 AWS, GCP, Azure 등 Public Cloud 에서 운영하는 경우, * AWS 의 경우, Amazon Linux 를 추천합니다. * GCP 의 경우, Ubuntu 24.04 LTS (또는 이후의 최신 LTS 버전)를 추천합니다. -### QueryPie Container 용 VM 모델 +## QueryPie Container용 VM 모델 기본사양 : CPU 4 vCPUs AMD64 Architecture, Memory 15 GiB 이상, Disk 100 GiB, CPU AMD @@ -33,7 +35,7 @@ QueryPie 서버를 AWS, GCP, Azure 등 Public Cloud 에서 운영하는 경우, * GCP Compute Engine : c4-standard-8, n4-standard-8 ( 또는 AMD64 아키텍처의 -standard-8 모델 ) * Disk IO 성능 : 높은 IOPS 의 Volume 을 적용합니다. AWS 의 EBS Provisioned IOPS SSD (io1) 또는 그 이상 성능의 Volume 을 적용합니다. -### QueryPie MySQL +## QueryPie MySQL 기본사양 : CPU 2 vCPUs, Memory 16 GiB 이상, Disk 100 GiB 이상 @@ -48,7 +50,7 @@ QueryPie 서버를 AWS, GCP, Azure 등 Public Cloud 에서 운영하는 경우, * Disk IO 성능 : 높은 IOPS 의 Volume 을 적용합니다. AWS 의 EBS Provisioned IOPS SSD (io1) 또는 그 이상 성능의 Volume 을 적용합니다. * Disk 용량 : QueryPie 에서 기록하는 Audit Log 를 MySQL 에 저장합니다. Audit Log 가 기록되는 빈도, 평균 크기, 보관 기간에 따라, 저장공간의 크기를 적절히 산정할 필요가 있습니다. -### QueryPie Redis +## QueryPie Redis 기본사양 : CPU 2 vCPUs, Memory 1 GiB 이상 @@ -61,11 +63,11 @@ QueryPie 서버를 AWS, GCP, Azure 등 Public Cloud 에서 운영하는 경우, * AWS ElastiCache On-Demand Nodes : cache.t4g.medium 또는 비슷한 모델 -### Availability Zone 에 따른 VM 구성 방법 +## Availability Zone에 따른 VM 구성 방법 가용영역(Availability Zone)에 따라 VM 을 배치하고, VM 의 사양을 조정하는 방법을 안내합니다. -#### 운영환경에서는 가용영역 3개 (또는 4개) 에 각각 VM 을 생성하여 배치합니다. +### 운영환경에서는 가용영역 3개 (또는 4개)에 각각 VM을 배치 하나의 가용영역에 VM 이 집중되지 않도록, 각 가용영역에 골고루 VM 을 분산하여 배치합니다. @@ -73,7 +75,7 @@ QueryPie 서버를 AWS, GCP, Azure 등 Public Cloud 에서 운영하는 경우, 서비스 이용량이 높아지면, VM 의 수를 늘여, 평소에 측정되는 최대 이용량이 일정 수준 이하를 유지하도록 조정합니다. 구체적인 조정 기준은 아래에서 설명합니다. -#### 하나의 VM Instance 가 서비스를 중단하게 되더라도, 평소에 측정되는 최대 이용량을 처리 가능하도록, VM 의 사양을 조정합니다. +### VM 장애 시에도 최대 이용량을 처리할 수 있도록 사양 조정 예를 들어, 3개의 VM 을 구성하여 서비스를 제공하는 경우, 2개의 VM 만으로 최대 이용량을 처리 가능하도록 VM 의 사양을 조정합니다. 2개의 VM 이 최대 이용량을 처리하는 시점에, CPU 사용량이 85% 를 넘지 않도록 조정합니다. @@ -93,7 +95,7 @@ VM 갯수를 늘이는 Scale-Out 구성을 적용하는 경우, 정상 운영시 VM 갯수를 늘이지 않고, 2개 또는 3개를 고정으로 두는 경우, 정상 운영시 최대 CPU 사용량으로 계산된 기준값보다 더 높은 실제 사용량을 보일 경우, VM 의 CPU 수를 늘이거나, Instance Type 을 고사양으로 변경하여, 계산된 기준값보다 더 낮은 실제 사용량을 보이도록 조정합니다. -#### Auto Scaling Group 설정을 적용하지 않습니다. +### Auto Scaling Group 사용 제한 서비스가 처리하는 트래픽, 부하의 정도에 따라 Upstream 서버를 자동으로 늘이거나 줄이는 Auto Scaling Group 설정을 적용하지 않습니다. @@ -105,9 +107,9 @@ Auto Scaling Group 을 적용하는 경우, Upstream 서버 수가 변경될 때 참조 - [HA 구성에서 Sticky Session이 왜 필요한가요?](https://querypie.atlassian.net/wiki/spaces/QCP/pages/894632097) -### 요구되는 성능에 대한 근거 +## 요구되는 성능에 대한 근거 -#### QueryPie Server 가 요구하는 컴퓨팅 자원의 유형 +### QueryPie Server가 요구하는 컴퓨팅 자원의 유형 QueryPie Server Container 와 MySQL 은 다음과 같은 유형의 작업을 처리하는데, 컴퓨팅 자원을 주로 사용합니다. @@ -117,7 +119,7 @@ QueryPie Server Container 와 MySQL 은 다음과 같은 유형의 작업을 처 * SSO Integration 에 따라, 주기적으로 다수 이용자의 목록을 전송 받고, 각 이용자의 QueryPie 계정 정보를 업데이트합니다. * External API 를 이용해, 다수의 DB, Server 자산을 등록하거나 변경하고, 접근제어 정책을 변경합니다. -#### QueryPie Container 가 요구하는 메모리 크기 +### QueryPie Container가 요구하는 메모리 크기 * QueryPie Container 는 초기 실행시에 약 7 GiB 의 메모리를 사용합니다. 이용자의 사용에 따라, Container 가 사용하는 메모리가 2~3 GiB 가량 증가할 수 있습니다. * Mongo, Document DB 에 접근하는 경우, 메모리 사용량이 1 GiB 이상 증가할 수 있습니다. @@ -125,7 +127,7 @@ QueryPie Server Container 와 MySQL 은 다음과 같은 유형의 작업을 처 * Audit Log 를 기록하는 과정에서, Container 내부에서 임시 파일을 생성하여 사용합니다. 이에 따라, Disk 장치를 위한 OS 의 Cache 를 위한 메모리를 1~2 GiB 가량 할당해 줄 필요가 있습니다. -### FAQ +## FAQ #### Q: 이용자 수에 따라 서버 처리용량을 추정하는 가이드를 제공해 주세요. From c6e5e3152d3e1b2e1819d47622177587f2968c91 Mon Sep 17 00:00:00 2001 From: JK Date: Fri, 6 Feb 2026 03:57:31 +0900 Subject: [PATCH 3/7] =?UTF-8?q?refactor:=20Community=20Edition=20=EB=B0=8F?= =?UTF-8?q?=20MCP=20=EB=AC=B8=EC=84=9C=20=EC=84=B9=EC=85=98=20=EC=88=98?= =?UTF-8?q?=EC=A4=80=20=EC=A1=B0=EC=A0=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - querypie-acp-community-edition.mdx: 이모지 제거, 섹션 수준 조정 (### → ##) - mcp-configuration-guide.mdx: 섹션 수준 조정 (### → ##, #### → ###) - querypieweburl.mdx: 문서 서두에 요약 추가 Co-Authored-By: Claude Opus 4.5 --- .../querypieweburl.mdx | 2 ++ .../querypie-acp-community-edition.mdx | 20 +++++------ .../mcp-configuration-guide.mdx | 34 +++++++++---------- 3 files changed, 29 insertions(+), 27 deletions(-) diff --git a/src/content/ko/installation/container-environment-variables/querypieweburl.mdx b/src/content/ko/installation/container-environment-variables/querypieweburl.mdx index e62e14850..a0a897b19 100644 --- a/src/content/ko/installation/container-environment-variables/querypieweburl.mdx +++ b/src/content/ko/installation/container-environment-variables/querypieweburl.mdx @@ -6,6 +6,8 @@ import { Callout } from 'nextra/components' # QUERYPIE_WEB_URL +QUERYPIE_WEB_URL 환경변수의 용도와 설정 방법을 안내합니다. + ## 개요 QUERYPIE_WEB_URL은 서비스 접근, 인증 연동, 데이터 다운로드, 외부 연동 및 Proxy 설정 등 다양한 경로에서 사용되어 필수로 설정이 필요합니다. diff --git a/src/content/ko/installation/querypie-acp-community-edition.mdx b/src/content/ko/installation/querypie-acp-community-edition.mdx index 5a241bc4b..b2b6f19dc 100644 --- a/src/content/ko/installation/querypie-acp-community-edition.mdx +++ b/src/content/ko/installation/querypie-acp-community-edition.mdx @@ -6,7 +6,7 @@ import { Callout } from 'nextra/components' # QueryPie ACP Community Edition -### 🧭 시작하기 전에 +## 시작하기 전에 **QueryPie Community Edition** 은 **QueryPie Enterprise** 에서 제공되는 핵심 기능을 체험할 수 있도록 합니다. @@ -19,7 +19,7 @@ import { Callout } from 'nextra/components' QueryPie는 일반적인 웹 애플리케이션 형태로 실행되며, 프록시 기반 네트워크 서버 기능도 포함하고 있습니다. -### 🖥️ 권장 서버 사양 +## 권장 서버 사양 QueryPie Community Edition의 원활한 설치 및 운영을 위해 다음과 같은 시스템 환경을 권장합니다. @@ -82,9 +82,9 @@ ARM64 Architecture CPU 환경 또는 macOS 환경은 개발자를 위한 시험 자세한 요구사항은 아래 문서를 참고하세요: [설치 전 준비사항](prerequisites) -### 🐳 설치 방법 +## 설치 방법 -#### 1. 터미널에서 명령 실행 +### 1. 터미널에서 명령 실행 Linux 서버의 터미널에 접속한 후, 홈 디렉터리에서 다음 명령어를 실행하세요: ``` @@ -108,12 +108,12 @@ bash <(curl -s https://dl.querypie.com/setup.v2.sh) -#### 2. 설치 중 라이선스 발급 받기 +### 2. 설치 중 라이선스 발급 받기 QueryPie Community Edition은 라이선스 등록이 필요합니다. 설치가 진행되는 동안 [라이선스 신청서를 제출](https://querypie.com/querypie/license/community/apply)하면, 신청 시 입력한 이메일 주소로 `.crt` 텍스트 파일이 발송됩니다. -#### 3. 설치 후 접속 +### 3. 설치 후 접속 설치가 완료되면 브라우저에서 다음 주소로 접속하세요: ``` @@ -124,7 +124,7 @@ https:// QueryPie가 설치된 Linux 서버의 IP 주소는 사용자 PC에서 접근 가능해야 합니다. -#### 4. 라이선스 등록 +### 4. 라이선스 등록 이메일로 받은 `.crt` 파일을 업로드하거나, PEM 형식의 텍스트 내용을 복사해 붙여넣으세요. @@ -144,7 +144,7 @@ PEM 형식 라이선스 입력 화면 * 라이선스는 신청자 본인에게 발급되며, 제3자에게 양도할 수 없습니다. -#### 5. 로그인 +### 5. 로그인 기본 계정으로 로그인하세요. 첫 로그인 시 보안을 위해 비밀번호 변경을 요청받습니다. @@ -169,7 +169,7 @@ qp-admin 계정으로 로그인 후 기본 암호를 다른 암호로 변경합 -#### 6. 설치 완료 🎉 +### 6. 설치 완료 설치가 성공적으로 완료되었습니다. 환경 설정을 위해 관리자 매뉴얼을 참고하여 주세요: [관리자 매뉴얼](../administrator-manual)
관리자 페이지로 이동하기 위해서는 오른쪽 상단의 `Go to Admin Page` 버튼을 누릅니다. @@ -233,7 +233,7 @@ docker compose ps ``` -### 💬 지원 및 문의 +## 지원 및 문의 QueryPie Community 설치 및 사용 중 궁금한 점이 있으면 [QueryPie AIP](https://app.querypie.com/)를 통해 직접 문의할 수 있습니다. 아래 절차에 따라 MCP에서 **QueryPie 고객센터** 프리셋을 설정하면, 채팅창에서 바로 지원을 받을 수 있습니다. diff --git a/src/content/ko/installation/querypie-acp-community-edition/mcp-configuration-guide.mdx b/src/content/ko/installation/querypie-acp-community-edition/mcp-configuration-guide.mdx index 4ba6bab0a..93152f507 100644 --- a/src/content/ko/installation/querypie-acp-community-edition/mcp-configuration-guide.mdx +++ b/src/content/ko/installation/querypie-acp-community-edition/mcp-configuration-guide.mdx @@ -6,7 +6,7 @@ import { Callout } from 'nextra/components' # MCP 설정 가이드 -### Overview +## Overview QueryPie ACP (Access Control Platform) Community Edition 11.5.0에 Remote MCP (Model Context Protocol) Server 기능이 추가 되었습니다. 이제 다양한 AI 코딩 어시스턴트에서 LLM을 사용해서 다양한 작업을 QueryPie ACP의 접근통제하에 안전하게 수행할 수 있습니다. @@ -18,22 +18,22 @@ MCP 관련 참고 자료 * [https://modelcontextprotocol.io/docs/develop/connect-remote-servers#understanding-remote-mcp-servers](https://modelcontextprotocol.io/docs/develop/connect-remote-servers#understanding-remote-mcp-servers) -#### 지원하는 AI 코딩 어시스턴트 +### 지원하는 AI 코딩 어시스턴트 * [Claude Code](https://docs.anthropic.com/en/docs/claude-code) * [gemini-cli](https://geminicli.com/) * [Cursor](https://www.cursor.com/) * [Windsurf](https://codeium.com/windsurf) -#### 사전 요구사항 +### 사전 요구사항 * 실행 중인 QueryPie ACP Community Edition 11.5.0 이상 * QueryPie ACP Community Edition에 생성된 유효한 사용자 계정 -### Integration +## Integration -#### MCP Server URL +### MCP Server URL AI 코딩 어시스턴트를 설정하기 위해, MCP Server 역할을 수행하는 QueryPie ACP 의 URL 을 입력하여야 합니다. 이 MCP Server URL 을 설정하는 것은 여러 AI 코딩 어시스턴트에서 공통적으로 수행하여야 합니다. @@ -45,7 +45,7 @@ AI 코딩 어시스턴트를 설정하기 위해, MCP Server 역할을 수행하 예시) `https://querypie.example.com/api/mcp` ______ -#### Claude Code +### Claude Code ##### 1. MCP 서버 주소를 추가합니다. @@ -128,7 +128,7 @@ claude mcp list 명령 수행 결과 “Clear authentication” 옵션으로 인증을 해제할 수 있습니다. ______ -#### gemini-cli +### gemini-cli ##### 1. 설정파일을 편집하여 MCP 서버 주소를 추가합니다. @@ -170,7 +170,7 @@ Gemini CLI에서 `/mcp auth` 명령을 사용하여 인증을 진행합니다. 자동으로 브라우저가 열리지 않는 경우 위 그림과 같이 화면에 출력되는 주소를 브라우저에 붙여넣어 진행할 수도 있습니다. ______ -#### Cursor +### Cursor ##### 1. 설정파일을 편집하여 MCP 서버 주소를 추가합니다. @@ -201,7 +201,7 @@ Cursor Settings에서 MCP 툴이 올바르게 연동 되는지 확인합니다. ______ -#### Windsurf +### Windsurf ##### 1. 설정파일을 편집하여 MCP 서버 주소를 추가합니다. @@ -232,9 +232,9 @@ Windsurf Agents 화면에서 MCP 툴이 올바르게 연동 되는지 확인합 -### QueryPie ACP Community Edition MCP server의 지원 Tool 목록 +## QueryPie ACP Community Edition MCP server의 지원 Tool 목록 -#### DAC (Database Access Control) +### DAC (Database Access Control) 데이터베이스 접근 및 쿼리 실행 관련 도구입니다. @@ -244,7 +244,7 @@ Windsurf Agents 화면에서 MCP 툴이 올바르게 연동 되는지 확인합 | `dac_execute_query` | 지정한 DB 연결에서 SQL 쿼리 실행. SELECT는 CSV 결과 반환 | ______ -#### SAC (Server Access Control) +### SAC (Server Access Control) 서버 접근 및 SSH 셸 세션 관련 도구입니다. @@ -260,7 +260,7 @@ ______ | `sac_stop_shell` | 셸 세션 종료 | ______ -#### KAC (Kubernetes Access Control) +### KAC (Kubernetes Access Control) Kubernetes 클러스터 관리 및 리소스 조작 도구입니다. @@ -293,21 +293,21 @@ Kubernetes 클러스터 관리 및 리소스 조작 도구입니다. | `kac_assign_role_me` | 현재 사용자에게 역할 할당 | ______ -### 권한 및 보안 +## 권한 및 보안 * 각 Tool은 ACP 권한 체계를 따릅니다. * ACP 에서 각 이용자에게 제공되는 DAC 의 DB 연결, Privilege Type 에 따른 접근 제어 정책, SAC 의 서버 접근 제어 정책, KAC 의 접근제어 정책에 따라, 자신에게 부여된 권한 범위 내에서만 Tool을 사용할 수 있습니다. * 모든 Tool 호출은 ACP 의 감사 로그에 기록됩니다. * ACP 의 IP 접근 제어 정책이 적용됩니다. -### 문제 해결 +## 문제 해결 -#### 연결 실패 +### 연결 실패 * ACP API 서버가 실행 중인지 확인 * 네트워크/방화벽 설정 확인 -#### 권한 오류 +### 권한 오류 * 해당 Tool에 필요한 권한이 있는지 확인 * 역할이 올바르게 할당되었는지 확인 From 6c9b6f5d9fb0d21675992580377751f0dc9c6a49 Mon Sep 17 00:00:00 2001 From: JK Date: Fri, 6 Feb 2026 04:00:09 +0900 Subject: [PATCH 4/7] =?UTF-8?q?refactor:=20AWS=20EKS=20=EC=84=A4=EC=B9=98?= =?UTF-8?q?=20=EA=B0=80=EC=9D=B4=EB=93=9C=20=EC=84=B9=EC=85=98=20=EC=88=98?= =?UTF-8?q?=EC=A4=80=20=EC=A1=B0=EC=A0=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 주요 섹션을 ### 에서 ## 로 변경 (1~6장) - 하위 섹션을 #### 에서 ### 로 변경 - 다른 설치 문서들과 일관된 섹션 구조 적용 Co-Authored-By: Claude Opus 4.5 --- .../installation/installing-on-aws-eks.mdx | 48 +++++++++---------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/src/content/ko/installation/installation/installing-on-aws-eks.mdx b/src/content/ko/installation/installation/installing-on-aws-eks.mdx index 1e58879f4..2ad56fcc2 100644 --- a/src/content/ko/installation/installation/installing-on-aws-eks.mdx +++ b/src/content/ko/installation/installation/installing-on-aws-eks.mdx @@ -6,19 +6,19 @@ import { Callout } from 'nextra/components' # AWS EKS 환경에서 설치하기 -### 1. 개요 +## 1. 개요 -#### 1.1 목적 +### 1.1 목적 * AWS EKS 클러스터에 QueryPie를 설치하고 구성하는 전체 과정 안내 * 안정적인 운영을 위한 설정 가이드 제공 -#### 1.2 대상 독자 +### 1.2 대상 독자 * Kubernetes 기본 개념(Pod, Service, Deployment 등)을 이해하고 있는 엔지니어 * AWS EKS 사용 경험이 있는 엔지니어 -#### 1.3 예상 소요 시간 +### 1.3 예상 소요 시간 * 전체 설치 과정: 약 1시간 * 환경 구성: 15분 @@ -26,16 +26,16 @@ import { Callout } from 'nextra/components' * QueryPie 설치: 20분 * 설치 검증 및 초기 설정: 10분 -### 2. 사전 요구사항 +## 2. 사전 요구사항 -#### 2.1 인프라 요구사항 +### 2.1 인프라 요구사항 * EKS 클러스터 * 권장 노드 사양: m7i.xlarge (4 vCPU, 16GB RAM) * Kubernetes 버전: 1.24 이상 * 필요 노드 수: 최소 1개 (프로덕션 환경은 3개 이상 권장) -#### 2.2 로컬 환경 준비사항 +### 2.2 로컬 환경 준비사항 AWS CLI 설치 및 구성 ```bash @@ -59,7 +59,7 @@ brew install kubectx # Context switching tool brew install fzf # Command-line fuzzy finder ``` -#### 2.3 접근 권한 요구사항 +### 2.3 접근 권한 요구사항 Container Registry 접근 권한 @@ -68,20 +68,20 @@ Container Registry 접근 권한 * 계정 정보 (Username/Password) * QueryPie 이미지 접근 권한 -#### 2.4 네트워크 요구사항 +### 2.4 네트워크 요구사항 * 인터넷 연결 (이미지 다운로드용) * EKS 클러스터 접근 가능한 네트워크 환경 * LoadBalancer 사용 가능한 환경 (Ingress 구성용) -### 3. 기본 컴포넌트 설치 +## 3. 기본 컴포넌트 설치 시작하기 전에 QueryPie를 설치를 위해 namespaces를 만듭니다. ``` kubectl create namespace querypie ``` -#### 3.1 MetaDB(MySQL) 설치 +### 3.1 MetaDB(MySQL) 설치 MySQL은 QueryPie의 메타데이터를 저장하는 데이터베이스로 사용됩니다. @@ -223,7 +223,7 @@ MySQL을 종료합니다. exit ``` -#### 3.2 Redis 설치 +### 3.2 Redis 설치 Redis는 QueryPie의 세션 및 캐시 저장소로 사용됩니다. 아래 내용으로 `redis.yml` 파일을 생성합니다. `{your-redis-password}` 에는 고객사의 정책에 따라 다른 값을 지정합니다. @@ -292,9 +292,9 @@ Redis Pod가 정상적으로 실행될 때까지 기다립니다. kubectl get pods -w -n querypie | grep redis ``` -### 4. QueryPie 설치 +## 4. QueryPie 설치 -#### 4.1 Secret 설정 +### 4.1 Secret 설정 ##### 4.1.1 Container Registry 인증 정보 등록 @@ -353,7 +353,7 @@ REDIS_PASSWORD={your-redis-password} kubectl create secret generic querypie-secret --from-env-file=querypie.env -n querypie ``` -#### 4.2 Helm Chart 설정 +### 4.2 Helm Chart 설정 ##### 4.2.1 Helm Repository 추가 @@ -548,7 +548,7 @@ config: skipCommandConfigFile: /app/arisa/skip_command_config.json ``` -#### 4.3 QueryPie 설치 +### 4.3 QueryPie 설치 Helm을 사용하여 QueryPie ACP 를 설치합니다. @@ -576,7 +576,7 @@ kubectl exec -it deployments/poc-querypie-tools -n querypie -- /app/script/migra ``` -#### 4.4 설치 확인 +### 4.4 설치 확인 Pod 상태를 확인합니다. ```bash @@ -601,9 +601,9 @@ kubectl port-forward -n querypie statefulsets/poc-querypie 80:80 이것으로 제품 설치 과정이 완료되었습니다. 수고하셨습니다~! -### 5. 문제 해결 가이드 +## 5. 문제 해결 가이드 -#### 5.1 설치 전 확인사항 +### 5.1 설치 전 확인사항 ##### 5.1.1 클러스터 접근 권한 확인 @@ -628,7 +628,7 @@ kubectl top nodes kubectl get storageclass ``` -#### 5.2 일반적인 문제 해결 +### 5.2 일반적인 문제 해결 ##### 5.2.1 Pod 상태 확인 @@ -680,7 +680,7 @@ kubectl get ingress -n querypie kubectl describe ingress -n querypie ``` -#### 5.3 리소스 모니터링 +### 5.3 리소스 모니터링 ```bash # Check pod CPU/Memory usage @@ -693,7 +693,7 @@ kubectl top nodes kubectl get pod -n querypie -o jsonpath='{.spec.containers[0].resources}' ``` -#### 5.4 설치 구성 확인 +### 5.4 설치 구성 확인 ```bash # Check ConfigMap @@ -707,7 +707,7 @@ kubectl get pv kubectl get pvc -n querypie ``` -#### 5.5 지원 요청 시 필요한 정보 +### 5.5 지원 요청 시 필요한 정보 문제 해결이 어려운 경우, 다음 정보를 수집하여 지원팀에 문의하세요: @@ -748,7 +748,7 @@ kubectl logs mysql-0 > mysql.log kubectl logs $(kubectl get pod -l app=redis -o jsonpath='{.items[0].metadata.name}') > redis.log ``` -### 6. 참고 자료 +## 6. 참고 자료 * [Amazon EKS Workshop](https://www.eksworkshop.com) * [Amazon EKS 문서](https://docs.aws.amazon.com/eks/) From 3822d1f7b34be97e612f27df390b6391f92bc984 Mon Sep 17 00:00:00 2001 From: JK Date: Fri, 6 Feb 2026 04:00:51 +0900 Subject: [PATCH 5/7] =?UTF-8?q?refactor:=20=EC=84=9C=EB=B2=84=20=EA=B5=AC?= =?UTF-8?q?=EC=84=B1=20=EC=9A=94=EA=B5=AC=EC=82=AC=ED=95=AD=20=EC=9A=94?= =?UTF-8?q?=EC=95=BD=ED=91=9C=20=EC=84=B9=EC=85=98=20=EC=88=98=EC=A4=80=20?= =?UTF-8?q?=EC=A1=B0=EC=A0=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 주요 섹션을 ### 에서 ## 로 변경 - 하위 섹션을 #### 에서 ### 로 변경 - 다른 문서들과 일관된 섹션 구조 적용 Co-Authored-By: Claude Opus 4.5 --- ...rver-configuration-requirements-summary.mdx | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/src/content/ko/installation/server-configuration-requirements/server-configuration-requirements-summary.mdx b/src/content/ko/installation/server-configuration-requirements/server-configuration-requirements-summary.mdx index 222472c13..495e230e6 100644 --- a/src/content/ko/installation/server-configuration-requirements/server-configuration-requirements-summary.mdx +++ b/src/content/ko/installation/server-configuration-requirements/server-configuration-requirements-summary.mdx @@ -6,9 +6,9 @@ title: '서버구성 요구사항 요약표' QueryPie 서버의 하드웨어 처리용량 요구사항에 대한 가이드를 간단하게 정리한 요약표입니다. -### 배포 환경별 권장 구성 +## 배포 환경별 권장 구성 -#### Public Cloud 환경 (AWS, GCP, Azure) +### Public Cloud 환경 (AWS, GCP, Azure) | 구성 요소 | 권장 사항 | | ------- | ------------------------------------------------------- | @@ -18,16 +18,16 @@ QueryPie 서버의 하드웨어 처리용량 요구사항에 대한 가이드를 | 캐시 서비스 | Managed Service 방식의 Redis (AWS ElastiCache 등) | | OS | Linux 배포판 (AWS: Amazon Linux, GCP: Ubuntu 24.04 LTS 권장) | -#### On-Premise 환경 +### On-Premise 환경 | 구성 요소 | 권장 사항 | | ------- | ----------------------------------------- | | 고가용성 구성 | L7 Load Balancer, L4 Load Balancer 적용 | | VM 인스턴스 | 2개 이상의 VM을 Upstream 서버로 구성 (Scale-Out 방식) | -### 컴포넌트별, 용량별 사양 +## 컴포넌트별, 용량별 사양 -#### QueryPie Container VM 사양 +### QueryPie Container VM 사양 | 구분 | 기본 사양 | 권장 사양 | | ------------------ | ----------------------------- | --------------------------------- | @@ -39,7 +39,7 @@ QueryPie 서버의 하드웨어 처리용량 요구사항에 대한 가이드를 | 디스크 IO 성능 | EBS General Purpose SSD (gp3) | EBS Provisioned IOPS SSD (io1) 이상 | | 권장 구성 | 기본사양 VM 2개 이상 | 권장사양 VM 2개 이상 | -#### QueryPie MySQL 사양 +### QueryPie MySQL 사양 | 구분 | 기본 사양 | 권장 사양 | | --------------- | ----------------------------- | --------------------------------- | @@ -50,7 +50,7 @@ QueryPie 서버의 하드웨어 처리용량 요구사항에 대한 가이드를 | 디스크 IO 성능 | EBS General Purpose SSD (gp3) | EBS Provisioned IOPS SSD (io1) 이상 | | 참고사항 | Managed Service 방식 권장 | Managed Service 방식 권장 | -#### QueryPie Redis 사양 +### QueryPie Redis 사양 | 구분 | 기본 사양 | 권장 사양 | | --------------- | --------------------- | --------------------- | @@ -59,7 +59,7 @@ QueryPie 서버의 하드웨어 처리용량 요구사항에 대한 가이드를 | AWS ElastiCache | cache.t4g.small | cache.t4g.medium | | 참고사항 | Managed Service 방식 권장 | Managed Service 방식 권장 | -### 메모리 사용량 참고사항 +## 메모리 사용량 참고사항 | 구분 | 사용량 | | ------------------------- | -------- | @@ -68,7 +68,7 @@ QueryPie 서버의 하드웨어 처리용량 요구사항에 대한 가이드를 | Mongo/Document DB 접근 시 추가 | 1 GiB 이상 | | OS 캐시용 추가 메모리 | 1~2 GiB | -### 성능 참고사항 +## 성능 참고사항 * 기본사양 VM 1대: DAC 기준 간단한 쿼리 초당 70건 이상 처리 가능 (1분에 4,200건, 1시간에 25만건) * 수백~수천 명의 이용자가 일상적인 가벼운 쿼리 실행 시 기본사양 VM 1-2대로 충분히 처리 가능 From 657ac3ba2bd23fba3b244331f7c4bbaa1cd33dd8 Mon Sep 17 00:00:00 2001 From: JK Date: Sat, 7 Feb 2026 15:03:25 +0900 Subject: [PATCH 6/7] =?UTF-8?q?refactor:=20=EC=84=9C=EB=B2=84=20=EC=9A=94?= =?UTF-8?q?=EA=B5=AC=EC=82=AC=ED=95=AD=20=EB=AC=B8=EC=84=9C=EC=97=90=20?= =?UTF-8?q?=EC=9A=94=EC=95=BD=20=ED=85=8C=EC=9D=B4=EB=B8=94=20=EC=B6=94?= =?UTF-8?q?=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - On-Premise VM 요구사항 문서에 컴포넌트별 사양 요약 테이블 추가 - Public Cloud 운영서버 요구사항 문서에 AWS 인스턴스 타입 요약 테이블 추가 Co-Authored-By: Claude Opus 4.5 --- .../on-premise-vm-requirements.mdx | 8 ++++++++ .../public-cloud-production-server-requirements.mdx | 8 ++++++++ 2 files changed, 16 insertions(+) diff --git a/src/content/ko/installation/server-configuration-requirements/on-premise-vm-requirements.mdx b/src/content/ko/installation/server-configuration-requirements/on-premise-vm-requirements.mdx index 45900d8a0..6c9337d8c 100644 --- a/src/content/ko/installation/server-configuration-requirements/on-premise-vm-requirements.mdx +++ b/src/content/ko/installation/server-configuration-requirements/on-premise-vm-requirements.mdx @@ -6,6 +6,14 @@ title: 'On-Premise VM 요구사항' On-Premise 물리서버의 Virtual Machine에서 QueryPie를 운영하기 위한 가이드입니다. +## 요약 + +| 컴포넌트 | 기본 사양 | 권장 사양 | +| --- | --- | --- | +| QueryPie Container VM | 4 vCPUs, 15 GiB Memory, 100 GiB Disk | 8 vCPUs, 30 GiB Memory, 100 GiB Disk | +| QueryPie MySQL VM | 2 vCPUs, 8 GiB Memory, 100 GiB Disk | 8 vCPUs, 32 GiB Memory, 100 GiB+ Disk | +| QueryPie Redis VM | 2 vCPUs, 1 GiB Memory | 2 vCPUs, 3 GiB Memory | + ## 개요 Production 환경의 운영을 위해 다음과 같은 구성을 권장합니다. diff --git a/src/content/ko/installation/server-configuration-requirements/public-cloud-production-server-requirements.mdx b/src/content/ko/installation/server-configuration-requirements/public-cloud-production-server-requirements.mdx index e2dc532ab..394813e42 100644 --- a/src/content/ko/installation/server-configuration-requirements/public-cloud-production-server-requirements.mdx +++ b/src/content/ko/installation/server-configuration-requirements/public-cloud-production-server-requirements.mdx @@ -6,6 +6,14 @@ title: 'Public Cloud 운영서버 요구사항' AWS, GCP, Azure 등 Public Cloud에서 QueryPie를 운영하기 위한 서버 구성 가이드입니다. +## 요약 + +| 컴포넌트 | 기본 사양 | 권장 사양 (높은 처리량) | +| --- | --- | --- | +| QueryPie Container VM | m6i.xlarge (4 vCPUs, 16 GiB) | m6i.2xlarge (8 vCPUs, 32 GiB) | +| QueryPie MySQL | db.r7g.large (2 vCPUs, 16 GiB) | db.r7g.xlarge (4 vCPUs, 32 GiB) | +| QueryPie Redis | cache.t4g.small (2 vCPUs, 1 GiB) | cache.t4g.medium (2 vCPUs, 3 GiB) | + ## 개요 Public Cloud에서는 다음과 같은 구성을 권장합니다. From 11f300a49a209da19df4e96c0eaff50c228eec0d Mon Sep 17 00:00:00 2001 From: JK Date: Sat, 7 Feb 2026 15:04:26 +0900 Subject: [PATCH 7/7] =?UTF-8?q?fix:=20=ED=99=98=EA=B2=BD=EB=B3=80=EC=88=98?= =?UTF-8?q?=20=EB=AC=B8=EC=84=9C=EC=9D=98=20=EB=A7=81=ED=81=AC=20=EA=B0=9C?= =?UTF-8?q?=EC=84=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - "Unknown Title" 링크 텍스트를 명확한 제목으로 수정 - 외부 Confluence 링크를 내부 문서 링크로 대체 (querypieweburl.mdx) Co-Authored-By: Claude Opus 4.5 --- .../ko/installation/container-environment-variables.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/ko/installation/container-environment-variables.mdx b/src/content/ko/installation/container-environment-variables.mdx index 96d7ba69d..17a046516 100644 --- a/src/content/ko/installation/container-environment-variables.mdx +++ b/src/content/ko/installation/container-environment-variables.mdx @@ -30,7 +30,7 @@ QueryPie Server Container를 실행하는 데 필요한 환경변수를 안내 | DB_DRIVER_CLASS | `org.mariadb.jdbc.Driver` | Meta DB 가 AWS Aurora 인 경우, Aurora Instance 부분 장애시 Failover 를 지원합니다.AWS Aurora 를 적용하여 Failover 기능을 사용하려는 경우, AWS에서 제공하는 전용 드라이버 `software.amazon.jdbc.Driver` 를 지정합니다. | | REDIS_NODES | | QueryPie Redis 에 연결하기 위한 Host, Port 정보를 입력합니다. 둘 이상의 Host, Port 정보를 입력하는 경우, `Host1:Port1,Host2:Port2` 와 같이, `,` 로 구분하여 입력할 수 있습니다.PoC 용도로 Single Machine 에 QueryPie Container, Redis Container 등을 모두 설치하는 경우, `host.docker.internal:6379` 을 입력하면 됩니다.Host 는 IP Address 형태를 입력하여도 되고, FQDN 을 입력하여도 됩니다. | | REDIS_PASSWORD | | 권장하는 값: 16-char random string via `openssl rand -hex 8`Redis Password | -| DAC_SKIP_SQL_COMMAND_RULE_FILE | `skip_command_config.json` | 3rd Party Tool (DataGrip, DBeaver 등 워크벤치 툴) 에서 이용자가 입력하는 쿼리가 아닌, 툴이 자동으로 실행하는 SQL Query 를 Audit Log 에 남기지 않도록 설정합니다.툴이 자동으로 실행하는 SQL Query 는 구문의 패턴이 정해져 있다는 의미에서, 정형화된 Query 라고 부르기도 합니다.이러한 정형화된 Query 를 Audit Log 에 남기지 않도록 설정하면, 이용자가 체감하는 3rd Party Tool 의 응답속도가 빨라지게 됩니다. QueryPie Server 의 성능 부하를 감소시키는데, 도움이 됩니다.자세한 내용은 [Unknown Title#환경변수 추가.2](https://chequer.atlassian.net/wiki/spaces/QCP/pages/851346405/10.2.x#%ED%99%98%EA%B2%BD%EB%B3%80%EC%88%98-%EC%B6%94%EA%B0%80.2) 문서에서 확인할 수 있습니다. | +| DAC_SKIP_SQL_COMMAND_RULE_FILE | `skip_command_config.json` | 3rd Party Tool (DataGrip, DBeaver 등 워크벤치 툴) 에서 이용자가 입력하는 쿼리가 아닌, 툴이 자동으로 실행하는 SQL Query 를 Audit Log 에 남기지 않도록 설정합니다.툴이 자동으로 실행하는 SQL Query 는 구문의 패턴이 정해져 있다는 의미에서, 정형화된 Query 라고 부르기도 합니다.이러한 정형화된 Query 를 Audit Log 에 남기지 않도록 설정하면, 이용자가 체감하는 3rd Party Tool 의 응답속도가 빨라지게 됩니다. QueryPie Server 의 성능 부하를 감소시키는데, 도움이 됩니다.자세한 내용은 [릴리스 노트 10.2.x - 환경변수 추가](https://chequer.atlassian.net/wiki/spaces/QCP/pages/851346405/10.2.x#%ED%99%98%EA%B2%BD%EB%B3%80%EC%88%98-%EC%B6%94%EA%B0%80.2) 문서에서 확인할 수 있습니다. | ## 더 이상 사용되지 않는 환경변수 @@ -70,7 +70,7 @@ Web Console 에 접근하기 위한 QueryPie 의 URL 주소입니다.
(예 이 URL 은 아래의 용도로 사용됩니다. * SSO Integration 의 인증 과정에서, callback 주소로 사용됩니다. * Web Console 에서 User Agent 를 내려받는 링크에 사용됩니다. -* 그 외 자세한 용도는, [https://chequer.atlassian.net/wiki/spaces/QCP/pages/876937310](https://chequer.atlassian.net/wiki/spaces/QCP/pages/876937310) 를 참조하시기 바랍니다. +* 그 외 자세한 용도는, [QUERYPIE_WEB_URL](container-environment-variables/querypieweburl) 문서를 참조하시기 바랍니다.