AriWeb-Suite/modules/webmaker/docs/CONFIG.md

설정 파일과 초기 설정 페이지 — v1.5.7 (v1.5.11 개정)

AI Webmaker v1.5.11 · 2026-10-14 · 대상: 운영자·설치 담당자

v1.5.11: 설정 페이지 기본 포트 8795(모든 인터페이스, 겹치면 다음 포트 자동), 서비스의 /setup 도 접속 토큰으로 열림, 맨 위에 설치 점검표·관리자 계정·AI 엔진 인증 카드. 처음 설치 절차는 FIRST-INSTALL.md.

1. 무엇이 바뀌었나 (요구 1·2·3)

	1.4.18 까지	1.5.7 부터
서비스 공개 주소, 소스 저장소(Gitea) 주소, AI 실행 파일 경로 같은 환경 정보	systemd 유닛의 Environment= 줄 (PUBLIC_BASE_URL, SITES_GIT_REMOTE …) — 바꾸려면 서버에서 유닛을 편집하고 daemon-reload	설정 파일 data/config.json (권한 0600) — 웹 초기 설정 페이지·관리자 콘솔·명령줄에서 바꾼다
처음 설치할 때 모르는 값	설치 스크립트가 빈 값·임시 값으로 유닛을 써 두고 나중에 사람이 고침	설치가 끝나면 초기 설정 페이지 주소(별도 포트, 기본 8795 — 1.5.7 은 3081) 를 알려 주고 거기서 입력. 1.5.11: 설치 점검표가 끝나기 전에는 서비스 첫 화면도 /setup 으로 넘어간다
기존 운영 서버	—	1.5.7 로 올린 첫 기동 때 유닛의 환경 변수를 그대로 설정 파일에 옮겨 적는다. 운영 값은 바뀌지 않는다
비밀값(토큰·비밀번호)	일부는 유닛, 일부는 보관소	모두 암호화 보관소(data/credentials.json, lib/vault.js). 설정 파일에는 쓰지 않는다

유닛에는 배포 때 정해지는 값만 남는다: PORT, HOST, SITES_ROOT, DATA_ROOT(선택), PATH, HOME, NODE_ENV. 이 값들은 설정 파일에서 바꿀 수 없다(읽기 전용으로 보임) — 포트·경로는 웹서버(nginx/Caddy) 프록시 설정과 함께 바뀌어야 하기 때문이다.

2. 설정 파일 (lib/config.js)

• 경로: 환경 변수 WEBMAKER_CONFIG > <DATA_ROOT>/config.json (기본 앱 폴더의 data/config.json).
• 형식: { "version": 1, "updatedAt", "updatedBy": "setup|cli|migrate:env", "values": { "<그룹>.<항목>": 값 } }
• 우선순위: 설정 파일 > 환경 변수(유닛) > 기본값. 배포 때 정해지는 값(runtime.*)만 환경 변수가 우선.
• 서비스는 기동 맨 처음 config.apply() 로 파일 값을 process.env 에 넣는다. 그래서 코드의 다른 부분(process.env.PUBLIC_BASE_URL 등)은 그대로다. 파일이 바뀌면(설정 페이지·CLI) 다음 호출부터 새 값을 읽지만, 기동 때 한 번만 읽는 모듈의 값(아래 표 "재시작")은 서비스를 재시작해야 적용된다.
• 파일이 없으면 지금 환경 변수로 파일을 만든다(migrateFromEnv). 1.5.7 로 올린 기존 서버에서 이 일이 한 번 일어난다 ([config] 설정 파일을 환경 변수에서 만들었습니다 로그).

항목표

그룹	항목 (key)	환경 변수	뜻	기본값	재시작
서비스	service.publicBaseUrl	PUBLIC_BASE_URL	사용자가 접속하는 주소. 생성 사이트의 위젯·통계·웹메일 안내 파일이 이 주소를 부른다 (필수)	http://192.168.20.66	○
	service.formBaseUrl	FORM_BASE_URL	폼 접수 서버 주소 (비우면 공개 주소)		○
	service.adminUsers	ADMIN_USERS	관리자로 취급할 아이디(쉼표)		○
	service.systemdUnit	WEBMAKER_SERVICE	설정 페이지 "서비스 재시작" 이 재시작할 유닛 (설치 스크립트가 넣음)
	service.setupPort / setupBind	WEBMAKER_SETUP_PORT / _BIND	초기 설정 페이지 포트·바인드 (lan = 첫 사설 IPv4, 0.0.0.0 = 전체, 또는 특정 IP)	3081 / lan	(setup 서비스)
실행 환경 (읽기 전용)	runtime.port host sitesRoot dataRoot statsLog	PORT HOST SITES_ROOT DATA_ROOT STATS_LOG	배포 때 정해지는 값	3080 / 127.0.0.1 / /var/www/sites / …	—
AI 엔진	ai.claudeBin codexBin	CLAUDE_BIN CODEX_BIN	실행 파일 (비우면 자동 탐색)		○
	ai.claudeModel claudeMaxTurns openaiMaxTurns allowInsecureTls	CLAUDE_MODEL CLAUDE_MAX_TURNS OPENAI_ENGINE_MAX_TURNS CLAUDE_ALLOW_INSECURE_TLS	설치 기본 모델·턴 상한·TLS 완화	claude-opus-5-5 / 80 / 60 / 켬	○
	ai.codexUnsafe	CODEX_UNSAFE	v1.6.31: 샌드박스를 만들 수 없을 때 기본은 작업 거부(fail-closed). true 면 샌드박스 없이 실행(위험)	false	○
	ai.maxJobMinutes maxConcurrentJobs	WM_MAX_JOB_MINUTES WM_MAX_CONCURRENT_JOBS	v1.6.31: 한 AI 작업 최대 시간(분, 15분 무출력도 중단) · 서버 전체 동시 AI 작업 수(넘으면 429)	45 / 4
	ai.allowInsecureTls	CLAUDE_ALLOW_INSECURE_TLS	v1.6.31 부터 기본 false(claude 자식의 TLS 검증 유지). 사내 프록시·자체 서명 인증서 환경에서만 true	false	○
서비스(보안)	service.trustedProxies	WM_TRUSTED_PROXIES	v1.6.31: 이 IP 에서 온 연결의 X-Forwarded-For 만 클라이언트 IP 로 믿음(속도 제한·기록). 비우면 루프백만
	service.internalAllow	WM_INTERNAL_ALLOW	v1.6.31: 사용자가 넣는 주소·제공자 URL 이 사설/내부 주소여도 허용할 host:port 목록(쉼표) — 사내 Gitea·Arimail·AI 서버. 그 밖의 내부 주소는 차단
	service.siteOrigin	WM_SITE_ORIGIN	v1.6.31: 생성 사이트 전용 origin(예약 — 사용자 결정 뒤 연결, 비우면 같은 origin)		○
	ai.codexSandbox	CODEX_SANDBOX	codex 샌드박스: auto(커널이 비특권 user namespace 를 허용하면 workspace-write, 아니면 없이 — Ubuntu 24.04 기본 kernel.apparmor_restrict_unprivileged_userns=1 에서는 샌드박스 쓰기가 모두 실패) / workspace-write / none	auto	(다음 작업부터)
소스 보관 (Gitea)	source.provider	SOURCE_PROVIDER	연동 모듈 (gitea / none)	gitea
	source.remote web prefix	SITES_GIT_REMOTE SITES_GIT_WEB SITES_GIT_PREFIX	푸시 주소·웹 주소·브랜치 접두어	/ / sites	(다음 커밋부터)
	source.apiUrl user repo	GITEA_API_URL GITEA_USER GITEA_REPO	API 주소·계정·저장소 (선택)	/ webmaker / webmaker/sites
	source.token	— (보관소 gitea)	API 토큰 (install-gitea.sh 가 만듦)
메일 연동 (Arimail)	mail.provider	MAIL_PROVIDER	연동 모듈 (none / arimail)	none
	mail.url apiUrl domain adminLogin	ARIMAIL_URL ARIMAIL_API_URL ARIMAIL_DOMAIN ARIMAIL_ADMIN_LOGIN	공개 주소·내부 API 주소·메일 도메인·관리자 ID	/ / / admin
	mail.adminPassword	— (보관소 arimail)	관리자 비밀번호
SSL	ssl.acmeDir acmeWaitMin	WM_ACME_DIR WM_ACME_WAIT_MIN	와일드카드 인증서 작업 폴더·수동 DNS 대기(분)	/var/tmp/webmaker-acme / 40	○
한도	limits.copyMaxPages copyMaxAssets	COPY_MAX_PAGES COPY_MAX_ASSETS	사이트 복사 상한	300 / 5000	○
외부 API (고급)	endpoints.*	RESEND_API_BASE OPENPROVIDER_API_BASE GOOGLE_API_BASE GOOGLE_TOKEN_URL INDEXNOW_ENDPOINT	시험용 대체 주소	실제 서비스 주소

관리자 콘솔 › 설정의 값(모델 등급·환율·마진·메일 발송 키·도메인 요율·DNS 공급자·등록 업체(v1.5.36) …)은 그대로 data/settings.json 이다. 설정 파일은 "서비스가 돌아가는 환경" 만 다룬다.

3. 초기 설정 페이지 (setup-server.js, 요구 2)

• 별도 systemd 서비스 webmaker-setup 이 설정 파일의 service.setupPort(기본 8795, v1.5.11; 겹치면 8796… 을 차례로 잡고 설정 파일에 기록)·setupBind(기본 0.0.0.0 — 공인 IP 만 있는 서버에서도 http://<IP>:8795/ 로 접속; 사설망만 열려면 lan = 첫 사설 IPv4, 도커 브리지 등 가상 인터페이스 제외) 로 전용 페이지를 연다. 설치 스크립트(deploy/install.sh, deploy/remote-install.sh, deploy/remote-update.sh)가 설치·기동하고, 끝나면 접속 주소를 알려 준다: http://<서버 IP>:8795/?token=<접속 토큰> (node scripts/config.js setup-url 로 언제든 다시 본다)
• 인증: 접속 토큰(data/setup.token, 0600 — 처음 기동 때 생성) 또는 웹메이커 관리자 계정 로그인. 세션은 12시간 쿠키. 로그인 시도는 IP 당 15분 10회.
• 같은 화면이 서비스 안에도 있다: https://<서비스>/setup (v1.5.11: 로그인 없이 열리고 화면 안에서 접속 토큰 또는 관리자 계정으로 들어온다 — 인증 코드 lib/setupauth.js 를 두 서버가 공용) 과 관리자 콘솔 › 시스템 설정 탭. 화면 코드는 public/setup.js 하나, API 는 lib/setupapi.js 하나다 (/api/setup/* ↔ /api/admin/config/*).
• 화면 (v1.5.11 맨 위): 설치 점검표(관리자 비밀번호·AI 엔진 인증·서비스 공개 주소 — lib/setupstate.js; 필수 항목이 남아 있으면 서비스 첫 화면 /·/login 이 /setup 으로 302, 끄기 service.setupRedirect=off, 우회 /login?direct=1), 관리자 계정(목록·마지막 로그인, 기본 관리자 admin/admin 만들기, 비밀번호 재설정, 새 관리자), AI 엔진 인증(Claude 서버 로그인/OAuth 토큰/API 키 저장·확인, OpenAI API 키/codex 로그인). 이어서 상태 카드(웹메이커 서비스·설정 페이지 서비스·Gitea·Arimail·Claude(실행 파일+인증)·Codex·Resend, "연결 확인"), 그룹별 설정 카드(출처 배지: 설정 파일/환경 변수/기본값, 재시작 표시, 비밀값은 힌트만), "이 묶음 저장"·"바뀐 값 모두 저장", 서비스 재시작(실행 중 AI 작업이 끝날 때까지 기다린 뒤 sudo systemctl restart), "환경 변수에서 옮겨 적기", 연동 서비스 설치·등록 명령 안내.
• 재시작 권한: 설치 스크립트가 /etc/sudoers.d/webmaker-setup 에 systemctl restart <유닛> 만 허용하는 줄을 둔다. 없으면 화면이 수동 명령을 알려 준다.
• 방화벽: v1.5.11 부터 설치·갱신 스크립트가 ufw 에 설정 페이지 포트(8795)를 허용하고 1.5.7 의 3081 사설망 규칙은 지운다(FQDN 을 모르는 서버에서도 http://<IP>:8795/ 가 기본 접속 위치). 접속은 토큰·관리자 로그인·시도 제한(IP 당 15분 10회)으로 보호되지만 관리 화면이므로, 점검이 끝나면 sudo ufw delete allow 8795/tcp 로 닫거나 service.setupBind=lan 으로 바꿔도 된다(서비스 안 /setup·관리자 콘솔 탭은 그대로).
• 새 설정 항목(v1.5.11): service.setupRedirect(auto/off), service.allowSignup(기본 켬 — 끄면 로그인 화면의 회원가입 탭이 사라지고 API 는 403 "회원가입이 닫혀 있습니다").
• API(v1.5.11, lib/setupapi.js): GET <base>/ready 점검표, POST <base>/admin/bootstrap|create|password, PUT <base>/ai/claude|openai. 명령줄: node scripts/admin.js bootstrap.

4. 명령줄 (scripts/config.js)

node scripts/config.js list                     # 전체 값과 출처
node scripts/config.js get service.publicBaseUrl
node scripts/config.js set service.publicBaseUrl https://webmaker.example.com   # 여러 쌍 가능
node scripts/config.js set mail.adminPassword '비밀번호'                          # 비밀값 → 보관소
node scripts/config.js unset source.apiUrl
node scripts/config.js import-env --unit /etc/systemd/system/webmaker.service   # 유닛 → 파일 (없는 항목만)
node scripts/config.js check                    # 필수 값 점검 (없으면 종료 코드 2)
node scripts/config.js setup-url                # 초기 설정 페이지 주소(토큰 포함)

환경 변수 DATA_ROOT·WEBMAKER_CONFIG 를 서비스와 같게 준다(기본 앱 폴더의 data/).

5. 기존 서버 올리기 (요구 3)

1. deploy/remote-update.sh <ssh> <앱 폴더> <유닛> — 코드 갱신·재시작 뒤 (a) 유닛의 환경 변수를 설정 파일로 옮기고 (b) webmaker-setup 서비스를 설치·기동하고 (c) deploy/install-services.sh --check 로 이미 설치된 Gitea·Arimail 을 등록한다. 서비스 기동 로그에 [config] 설정 파일을 환경 변수에서 만들었습니다 가 한 번 찍힌다.
2. 이후 유닛의 Environment=PUBLIC_BASE_URL=…, SITES_GIT_* 줄은 참고용이다 — 설정 파일이 우선한다. install-gitea.sh 를 다시 실행하면 SITES_GIT_* 줄을 유닛에서 지운다.
3. 다른 서버로 DB 를 복사할 때(remote-install.sh) 설정 파일과 토큰은 복사하지 않는다(서버마다 다른 값).

6. 자주 나는 메시지

메시지	원인	해결
[config] 설정 파일: … 로그만 있고 값이 바뀌지 않음	바꾼 항목이 "재시작 후 적용" 항목	설정 페이지의 "서비스 재시작" 또는 sudo systemctl restart <유닛>
설정 페이지 "서비스 재시작" → 재시작 실패: sudo: a password is required	sudoers 규칙 없음	deploy/install.sh/remote-update.sh 다시 실행(규칙 생성) 또는 서버에서 직접 재시작
접속 토큰이 맞지 않습니다	토큰이 바뀜(data/setup.token 삭제·재생성)	node scripts/config.js setup-url 로 새 주소, 또는 관리자 계정으로 로그인
<항목>은(는) 배포 때 정해지는 값이라 여기서 바꿀 수 없습니다	runtime.* 항목 저장 시도	유닛과 웹서버 설정을 함께 고친 뒤 재시작
<항목>은(는) http:// 또는 https:// 로 시작하는 주소여야 합니다 등	형식 오류	안내대로 수정. 저장은 전체가 검증을 통과했을 때만 된다

7. 백업 · 복구 (v1.6.31, 요구 29)

• deploy/remote-update.sh·deploy/install.sh 가 재시작 전에 node scripts/backup-data.js --tag update 를 실행해 DATA_ROOT 전체를 DATA_ROOT/backups/<UTC시각>-update.tar.gz(0600) 로 묶는다(최근 10개 보관, --keep N, --list). sites/ 의 git 저장소와 통계 로그는 크기 때문에 제외하지 않고 그대로 들어간다 — 용량이 크면 --keep 을 줄인다.
• 복구: 서비스를 멈추고(sudo systemctl stop <유닛>) tar -xzf DATA_ROOT/backups/<파일> -C DATA_ROOT 뒤 재시작. 특정 파일만 되돌릴 때는 DATA_ROOT/<파일>.bak(직전 저장본) 을 먼저 본다. 손상 파일 목록은 서버 기동 로그 [jsonstore] 와 관리자 콘솔 › 운영 복구에 보인다.
• 두 운영 서버는 DATA_ROOT 가 다르므로(bear: 앱 폴더 data/, hostinger: /data/webmaker) 백업도 각자 서버에만 남는다 — 서로 복사하지 않는다.