프로덕션에 배포하기

TLS, 리버스 프록시, 라이선스 도메인, 서비스 관리자, 백업, Content-Security-Policy와 격리 헤더, 그리고 SQLly Embedded 프로덕션 체크리스트.

로컬호스트에서는 기본 설정이 그대로 작동합니다. 프로덕션 환경에서는 브리지를 TLS 뒤에 두고, 라이선스를 도메인에 바인딩하며, 관리 API를 비공개로 유지하고, 모든 것을 서비스로 실행해야 합니다. 이 페이지에는 해당 설정, 구성 및 체크리스트가 있습니다.

권장 구성

  • 하나의 호스트 또는 사설 네트워크 앱과 브리지를 위한 자리입니다. 관리 API는 (127.0.0.1:8445) 오직 앱에서만 접근할 수 있어야 합니다.
  • 리버스 프록시 (nginx, Caddy, IIS, 클라우드 로드 밸런서)가 TLS를 종료하고 다음과 같은 경로에서 WebSocket 업그레이드를 전달합니다 /sqlly/proxy 브리지의 --bind 리스너.
  • 같은 프록시가 SQLly 페이지와 다음을 포함한 앱을 담당합니다 web/ 번들까지 제공하므로 모든 것이 라이선스 도메인 안에서 동일 출처로 처리됩니다.
  • 브리지에는 다음이 필요합니다 sqlly.app로의 아웃바운드 HTTPS (연결된 라이선스만 해당) 및 데이터베이스에 대한 네트워크 액세스. 브라우저는 절대로 데이터베이스나 엔진에 접근하지 않습니다.

리버스 프록시

엔진엑스
location /sqlly/proxy {
    proxy_pass http://127.0.0.1:8444/proxy;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header Origin $http_origin;      # the bridge checks it against your licensed domain
    proxy_read_timeout 1h;                     # long-running queries and idle editors
    proxy_send_timeout 1h;
}
caddy
portal.example.com {
    handle /sqlly/proxy {
        rewrite * /proxy
        reverse_proxy 127.0.0.1:8444
    }
    reverse_proxy 127.0.0.1:3000   # your app
}

이어서 브리지를 다음 옵션으로 시작합니다: --public-url wss://portal.example.com/sqlly/proxy 그래서 모든 실행 토큰이 SQLly에 어디로 연결할지 알려 줍니다. 프록시를 건너뛰려면 브리지에 --tls-cert 그리고 --tls-key 를 지정하면 브리지가 직접 wss:// 그 자체.

서비스로 실행

systemd: /etc/systemd/system/sqlly-embedded.service
[Unit]
Description=SQLly Embedded bridge
After=network-online.target
Wants=network-online.target

[Service]
User=sqlly
EnvironmentFile=/etc/sqlly-embedded.env
ExecStart=/opt/sqlly-embedded/bin/sqlly-bridge embedded
Restart=on-failure
RestartSec=10
# systemd's default SIGTERM is a clean shutdown: the bridge releases its
# instance slot on sqlly.app at once.
TimeoutStopSec=30

[Install]
WantedBy=multi-user.target
/etc/sqlly-embedded.env (chmod 600)
SQLLY_EMBEDDED_LICENSE_KEY=sqe_…
SQLLY_EMBEDDED_MANAGE_TOKEN=…
SQLLY_EMBEDDED_DOMAIN=portal.example.com
SQLLY_EMBEDDED_PUBLIC_URL=wss://portal.example.com/sqlly/proxy
SQLLY_EMBEDDED_BIND=127.0.0.1:8444
SQLLY_EMBEDDED_MANAGE_BIND=127.0.0.1:8445
SQLLY_EMBEDDED_STATE_DIR=/var/lib/sqlly-embedded
SQLLY_EMBEDDED_ALLOW_LOCALHOST_ORIGINS=false

macOS에서는 같은 환경을 담은 launchd plist를 사용하세요. Windows에서는 다음을 실행하세요 sqlly-bridge.exe embedded 서비스 래퍼나 작업 스케줄러 아래에서 구동하세요. 컨테이너에서는 상태 디렉터리를 볼륨으로 마운트하세요. 브리지는 시작할 때 라이선스를 확인할 수 없으면 명확한 메시지와 함께 종료되므로, 재시작 정책이 sqlly.app에 닿을 때까지 계속 재시도합니다.

일반 중지 신호로 멈추세요. 브리지는 SIGTERM에서 깔끔하게 종료됩니다 (systemd, launchd 및 docker stop 가 보내는 정상 종료 요청), SIGINT(Ctrl-C), SIGHUP(터미널 창 닫힘, ssh 세션 끊김), Windows에서는 콘솔 창이 닫힐 때: 세션을 닫고 sqlly.app의 인스턴스 슬롯을 즉시 해제합니다. sqlly.app가 응답하지 않으면 몇 초간 재시도합니다. 강제 종료(SIGKILL, 크래시, 정전)는 슬롯이 40분 뒤 만료될 때까지 유지되며 그 전까지는 대체 브리지를 받아들이지 않습니다. 이 변경 전의 브리지는 SIGINT에서만 슬롯을 해제했으므로, 예전 브리지를 돌리고 있다면 다음을 KillSignal=SIGINT 를 systemd unit에 추가하거나 Docker에서 STOPSIGNAL SIGINT 도커에서.

모든 브리지 설정

각 플래그에는 환경 변수가 있으므로, 서비스 유닛이나 .env 파일이 전체 구성을 담을 수 있습니다.

플래그환경기본값의미
--license-keySQLLY_EMBEDDED_LICENSE_KEY없음Embedded 페이지에서 연결한 라이선스 키.
--license-fileSQLLY_EMBEDDED_LICENSE_FILE없음오프라인 라이선스 파일. sqlly.app에 접속하지 않습니다. 키와 파일은 둘 중 하나만 지정하세요. 둘 다 없으면 연결된 키를 쓰고, 그것도 없으면 브리지가 라이선스 없이 시작합니다.
--domainSQLLY_EMBEDDED_DOMAIN없음첫 체크인에서 아직 연결되지 않은 라이선스를 연결하고, 라이선스가 다른 곳에 연결되어 있으면 시작을 거부합니다.
--bindSQLLY_EMBEDDED_BIND0.0.0.0:8444브라우저 WebSocket 리스너(경로 /proxy). 리버스 프록시 뒤에서 루프백을 사용하세요.
--public-urlSQLLY_EMBEDDED_PUBLIC_URLws://localhost:<port>/proxy브라우저가 사용하는 URL입니다. 모든 실행 토큰과 함께 반환됩니다.
--manage-bindSQLLY_EMBEDDED_MANAGE_BIND127.0.0.1:8445관리 API 리스너. 비공개로 유지하세요: 자격 증명을 포함합니다.
--manage-tokenSQLLY_EMBEDDED_MANAGE_TOKEN필수관리 API용 베어러 토큰, 16자 이상.
--tls-cert, --tls-keySQLLY_EMBEDDED_TLS_CERT, SQLLY_EMBEDDED_TLS_KEY없음서빙 wss:// 직접 서비스합니다. 둘 다 지정하거나 둘 다 지정하지 마세요.
--state-dirSQLLY_EMBEDDED_STATE_DIR./sqlly-embedded-state프로필, 캐시된 권한, 연결된 키, 세션별 자격 증명 파일. 소유자 전용 권한으로 생성됩니다.
--engine-binarySQLLY_CLI_BIN브리지 옆에, 그다음 PATH그 sqlly-cli 브리지는 세션별로 실행됩니다.
--max-sessionsSQLLY_EMBEDDED_MAX_SESSIONS64이 호스트에서 동시에 실행할 수 있는 엔진 수의 상한입니다.
--allow-localhost-originsSQLLY_EMBEDDED_ALLOW_LOCALHOST_ORIGINStrue라이선스 도메인 외에도 로컬호스트 오리진을 허용합니다. 프로덕션에서는 false 운영 환경에서.
--token-ttl-secondsSQLLY_EMBEDDED_TOKEN_TTL_SECONDS600기본 시작 토큰 유효 기간.
--store-urlSQLLY_STORE_URLhttps://sqlly.app체크인이 모이는 곳입니다. 개발 외부에서는 그대로 두세요.
--allow-file-enginesSQLLY_EMBEDDED_ALLOW_FILE_ENGINESfalse파일 기반 엔진(SQLite, DuckDB) 프로필을 허용합니다. 꺼져 있으면 다음 오류와 함께 거부됩니다: 400 invalid_profile. 다음을 참고하세요 파일 기반 엔진.
--query-logSQLLY_EMBEDDED_QUERY_LOGtrue쿼리 감사 추적 유지 (GET /manage/queries, <state-dir>/queries.jsonl). false 기록하지 않습니다. 자세한 내용은 쿼리 감사 추적.
--query-log-max-entriesSQLLY_EMBEDDED_QUERY_LOG_MAX_ENTRIES20000가장 최근에 완료된 쿼리를 메모리와 디스크에 보관(최소 100개).

상태 디렉터리와 호스트

상태 디렉터리에는 모든 프로필과 비밀번호, 캐시된 라이선스 승인, 연결된 설치의 키, 엔진에 전달되는 세션별 자격 증명 파일, 쿼리 감사 기록이 담깁니다. Linux와 macOS에서 브리지는 이 디렉터리를 소유자 전용으로 생성합니다 (0700, 파일 0600).

Windows에서는 브리지가 권한을 강화할 수 없습니다. 상태 디렉터리는 상위 폴더의 ACL을 상속하며, 브리지는 시작할 때 그 사실을 알리는 경고를 기록합니다. 상태 디렉터리는 서비스 계정만 읽을 수 있는 폴더 아래에 두세요. 예를 들어 다음 아래의 전용 디렉터리 %ProgramData% 전용 디렉토리를 두고 상속을 제거하며 서비스 계정만 접근 권한을 갖도록 ACL을 설정하고, 공유, 동기화되거나 사용자가 탐색할 수 있는 경로 아래에는 절대 두지 마십시오.

파일 기반 엔진

파일 기반 엔진은 기본적으로 비활성화되어 있습니다. 프로필 속의 SQLite나 DuckDB 연결은 브리지 호스트의 파일을 가리킵니다. 그 사용자는 그 파일을 읽고 새 파일을 만들 수 있고, 엔진 자체의 파일 함수를 통해 서비스 계정이 읽을 수 있는 다른 파일까지 닿을 수 있습니다. 그래서 브리지는 파일 기반 엔진이 관련된 프로필, 연결 테스트, 실행 토큰을 거부하는데, 그때의 응답 코드는 400 invalid_profile 그리고 problems[] 항목이 이유를 설명해 줍니다. 다음과 함께 실행하는 경우는 예외입니다 --allow-file-engines true이 기능은 전용으로 잠가 둔 서비스 계정과, 사용자가 접근하게 할 디렉터리에만 켜세요. 프록시 모드에서는 엔진이 여기에 더해 DuckDB 확장 다운로드와 외부 접근(파일 스캔, COPY, ATTACH) 설정은 SQLly가 여는 모든 DuckDB 인스턴스에 적용됩니다.

쿼리 감사 추적

브리지는 세션에서 실행하는 모든 쿼리와 행 편집을 기록합니다: 실행 토큰의 사용자와 프로필, 연결(이름, 서버, 엔진, 데이터베이스), SQL 텍스트, 시작 시각, 종료 방식, 소요 시간. 라이선스 문제로 거부된 요청은 라이선스 메시지를 남기며 실패로 기록되고, 세션이 닫힐 때 실행 중이던 것은 취소로 기록됩니다. 앱은 이 로그를 다음으로 읽습니다 GET /manage/queries, 최신 것부터, 사용자·프로필·상태·시간으로 필터링.

가장 최신 --query-log-max-entries 개 항목이 메모리와 <state-dir>/queries.jsonl (한 줄에 JSON 객체 하나씩, 소유자 전용으로 기록, 자동으로 압축)으로 저장되므로 기록은 재시작 후에도 유지됩니다. SQL 텍스트는 브리지 호스트에 평문으로 저장됩니다. 상태 디렉터리는 이미 들어 있는 프로필만큼 비공개로 유지하고, 다음을 설정하세요 --query-log false 쿼리 텍스트를 아예 남기면 안 되는 정책이라면입니다.

엔진 자체 로그

모든 sqlly-cli 엔진은 요청/응답 상관 로그를 자체 데이터 디렉터리에 기록합니다. 여기에는 모든 요청의 전체 SQL 텍스트가 담깁니다: ~/.local/share/sqlly/sqlly-engine.log (또는 $XDG_DATA_HOME/sqlly/sqlly-engine.log) Linux에서는, ~/Library/Application Support/SQLLY/sqlly-engine.log macOS에서는, %APPDATA%\SQLLY\sqlly-engine.log Windows에서는 소유자 전용으로 생성됩니다. 비밀번호, 토큰, 비밀 참조는 한 줄이 기록되기 전에 지워지고, ID, 서버, 사용자 이름, SQL은 그대로 남습니다. 다음을 설정하세요 SQLLY_ENGINE_LOG=<path> 브리지 환경에 설정하면(엔진들이 물려받습니다) 로그를 직접 관리하는 곳으로 옮길 수 있고, 아니면 SQLLY_ENGINE_LOG=/dev/null (NUL 을 Windows에서 설정하면 아무 것도 유지하지 않습니다. 엔진이 정상적으로 종료될 때만 로그는 마지막 줄로 잘립니다.

AI 공급자 설정

엔진은 환경에서 AI 공급자 설정을 가져옵니다 (SQLLY_LLM_PROVIDER, SQLLY_EMBEDDING_PROVIDER 및 관련 모델·키 변수). 최종 사용자의 IntelliSense와 AI 기능이 그 계정을 쓰게 하고 싶지 않다면 브리지 호스트에는 설정하지 마세요.

안전 플래그

프로필의 only_allow_select (클라이언트, 프로젝트 또는 환경 레이블에서 설정)과 연결의 safety.block_all_but_select 은 브리지 호스트에서 엔진이 강제합니다. 연결의 엔진 기준으로 SELECT 전용이 아닌 문과 모든 행 편집은 데이터베이스에 닿기 전에 "이 연결은 정책상 읽기 전용입니다"라는 이유로 거부되고, 브라우저가 무슨 소리를 하든 무관합니다. 그 밖의 안전 플래그(확인 대화상자, 롤백 래핑, 무한 UPDATE/DELETE 보호)는 사용자 브라우저 속 SQLly 클라이언트의 동작이지 서버 측 통제가 아닙니다. 실질적인 통제는 데이터베이스 권한입니다. 프록시된 로그인에는 그 사용자가 할 수 있어야 하는 일만 허용하세요.

크기 조정

열려 있는 각 SQLly 탭은 하나의 sqlly-cli 자체 데이터베이스 연결을 가진 엔진 프로세스. 메모리는 사람들이 하는 일을 따라갑니다: 결과 세트는 전체를 유지하지 않고 스트리밍되어 디스크로 넘겨지지만, 대규모 내보내기와 동시 탭이 많으면 합산됩니다. 호스트 크기는 최대 동시 탭 수(좌석 × 좌석당 탭 수 기준)에 맞게 설정하고 --max-sessions 를 안전장치로 사용하세요. 엔진은 필요 시 시작되고 탭이 닫히면 종료됩니다.

운영

  • 상태 디렉터리를 백업하세요. 이 디렉터리는 모든 프로필과 해당 자격 증명, 연결된 설치 키를 저장합니다. 백업을 비밀로 취급하세요.
  • 로그를 확인하세요 대하여 embedded license state: 모든 라이선스 전환은 상태 이름과 함께 기록됩니다. 다음을 폴링하세요 GET /manage/status 모니터링 수치와 함께 보고, 다음을 GET /healthz (토큰 없음)으로 활성 상태를 확인합니다.
  • 시스템 시간을 정확히 맞춰 두세요. 권한은 브리지 시각 기준 5분 안에 발급되어야 하니 NTP를 켜 두세요.
  • 함께 업그레이드하세요. 바꾸기 bin/ 그리고 web/ 같은 패키지 버전에서. 브리지를 재시작하면 열린 탭이 닫히며, 사용자는 새로 고침하여 다시 연결됩니다.
  • 관리 토큰 교체 새 값으로 브리지와 앱을 다시 시작하면 적용됩니다. 이미 만들어진 실행 토큰은 만료될 때까지 계속 동작합니다.
  • 도메인을 이동 중인가요? 임베디드 페이지에서 변경하고 새 값으로 브리지를 재시작하세요. --domain오프라인 라이선스는 도메인이 파일 안에 들어 있어서 새 파일이 필요합니다.

프로덕션 체크리스트

  • 브라우저 리스너 앞에 TLS 설정, 그리고 --public-url 다음으로 설정된 wss:// 주소.
  • SQLLY_EMBEDDED_DOMAIN 설정과 거기에 묶인 라이선스; --allow-localhost-origins=false.
  • 관리 API는 루프백이나 사설 네트워크에서; 토큰은 서버 측 시크릿으로만 관리.
  • 실행 토큰은 다음을 통해 페이지로 전달됩니다 SQLLY_PROXY_URL / SQLLY_PROXY_TOKEN 전역 변수에만 담기고 페이지 URL에는 절대 넣지 않습니다 (?token= 기록, 레퍼러, 웹 서버 로그에 남습니다).
  • --allow-file-engines 옵션은 잠금을 강화한 서비스 계정과 디렉터리를 마련하지 않는 한 꺼 둡니다.
  • 서비스 계정만 읽을 수 있는 상태 디렉터리(Linux/macOS에서는 소유자 전용, Windows에서는 명시적 ACL); --query-log 그리고 SQLLY_ENGINE_LOG 쿼리 텍스트 보관 정책에 따라 정해집니다.
  • 아니요 SQLLY_LLM_PROVIDER / SQLLY_EMBEDDING_PROVIDER 최종 사용자가 그 지출을 책임져야 하는 경우가 아니라면 브리지 환경에 두세요.
  • 브리지와 앱은 권한 없는 사용자 계정의 서비스로 실행되고, 실패 시 재시작하며, 안전하게 종료됩니다.
  • 상태 디렉터리는 영구 스토리지에 두고 소유자 전용으로 백업합니다.
  • SQLly 페이지 및 web/ COOP/COEP와 함께 제공되며, application/wasm, 그리고 브리지 오리진을 허용하는 CSP.
  • sqlly.app으로 나가는 HTTPS 허용(연결된 라이선스), NTP 켜짐.
  • 모니터링 켜짐 /manage/status: 다음과 같은 경우 알림 license.state 이(가) 다음 값이 아닐 때 알림을 보냅니다: ok.
  • 샘플 앱을 배포할 일이 있다면, 기본 관리자 비밀번호가 바뀌었습니다. 바꾸기 전까지는 루프백 밖으로 바인딩하기를 거부합니다.