AriWeb-Suite/docs/HAL-SETTINGS.md

HAL 통합 설정 관제 (Ariweb Suite 0.4.0)

HAL 이 도입 모듈·Node Agent 의 서버 단위 설정을 대신 관리한다. 개발 지시 Ariweb-Suitle_Dev-Order_v0.4.0.md(Oz).

1. 무엇을 관리하나

모듈	묶음	대표 항목
Webmaker 1.9.0	API 키·인증	auth.mode·auth.apiKey·auth.oauthToken·serviceApiKey·backlogKey·mail.apiKey·source.token·ariweb.secret·mail.adminPassword
	마진·가격 정책	marginPct·fx.mode/manualRate/spreadPct·signupCredit·maxEdits·defaultTier·tiers.*·signupApproval
	모델	internalRef·defaultModel·claudeModels·ai.*MaxTurns·ai.maxJobMinutes·ai.maxConcurrentJobs·ai.codexSandbox
	전체 적용 서비스	service.allowSignup·letsEncryptEmail·mail.fromName/defaultDomain/formBase·ariweb.portalUrl·endpoints.*·limits.*·ssl.acmeWaitMin
	서버별 설정(서버 범위만)	service.publicBaseUrl/formBaseUrl/siteOrigin/trustedProxies/internalAllow·ai.claudeBin/codexBin·source.*·mail.provider/url/apiUrl/domain/adminLogin/nickname/ip·ssl.acmeDir
AriMail 1.1.0	서버 단위	수·발신 방식, Resend, DNS 제공자, SMTP 중계, 내장 Haraka(서버 범위), 표시·동기화, 사용량 API, Ariweb SSO
Node Agent 0.4.0	Agent	heartbeatMs

• 관리하지 않는 것: AriMail 도메인별 관리(추가 도메인 설정·LIMIT_*·계정·메일함 — 메일 서버 사용자가 직접), Webmaker 사이트·회원·템플릿·테마 등 콘텐츠.
• 목록 정의: hal/settings/catalog.mjs(형식 text·int·number·bool·enum·list·url·path·secret, 범위, 재시작 필요).

2. 저장·유효값

• managed_settings(scope, module, key, value_json, is_secret) — scope global | server:<서버 id>. 비밀값은 HAL Vault managed:<scope>:<module>:<key> 에만, 행에는 참조만(마이그레이션 hal_0010_managed_settings).
• 유효값 = 전체 ← 서버 덮어쓰기. hash = sha256: + 모듈·유효값(비밀값 포함)의 정규 JSON sha256.
• managed_settings_state(server_id, module, applied_hash, applied_at, status, error, job_id) — 적용 상태. upToDate = 마지막 적용 hash 가 지금 유효값 hash 와 같음.

3. API(운영자 세션·CSRF)

경로	설명
GET /ops/api/settings	모듈 목록·설정 목록·모듈별 개요(배치 서버·적용 상태·적용 필요 수)
GET /ops/api/settings/:module?scope=	저장된 값(비밀값은 있음/없음), 서버 범위면 유효값·적용 상태
PUT /ops/api/settings/:module {scope, values}	저장(재인증 10분). null·빈 값 = 지정 삭제. 형식 오류·모르는 항목 400 bad_setting
DELETE /ops/api/settings/:module/:key?scope=	지정 삭제(재인증)
POST /ops/api/settings/:module/apply {serverIds, restart}	적용 작업(재인증). 대상 비우면 배치 서버 전체, 없으면 400 no_targets, 배치 안 된 서버 400 not_placed
GET /agent/v1/settings/:module	Agent HMAC. 자기 서버 범위의 유효값(비밀값 포함)·hash

감사 기록(settings.set·settings.apply)에는 키 이름만 남는다.

4. 적용 흐름

settings.apply(부모) → 서버마다 settings.apply.target → Agent module.configure:

1. 작업 payload 에는 hash 만(비밀값 없음). Agent 가 /agent/v1/settings/:module 에서 직접 받고 hash 가 다르면 settings_hash_mismatch(그 사이 설정이 바뀜).
2. <configDir>/hal-managed.json(0600) 원자 교체. 실행 계정이 다르면 module-as-user.sh write --mode 600. configDir: Webmaker /data/webmaker(DATA_ROOT), AriMail <appDir>/data(설정 파일 옆), Agent <dataDir>. 서버 facts configDirs 로 바꿀 수 있다.
3. restart 면 서비스 재시작·건강 확인(Agent 자신은 결과 보고 뒤 재시작).
4. 모듈이 파일을 적용하고 hal-managed.applied.json(hash·시각·항목·오류, 비밀값 없음)을 남기면 Agent 가 기다려(최대 45초) 결과에 싣는다. 모듈이 다른 hash·오류를 보고하면 module_apply_failed.

5. 모듈 쪽(HAL 0.4.0 대응)

• Webmaker 1.9.0 lib/hal-managed.js: 기동·파일 변경(10초 확인) 때 settings/config/보관소에 적용(auth·fx·tiers·mail 은 묶음 저장). 관리자 콘솔 설정·보관소·설정 페이지에서 관리 항목 409 managed_by_hal, 설정 탭 "HAL 관리" 안내.
• AriMail 1.1.0 server/hal-managed.mjs: 기본 도메인(서버) 설정에만 적용, LIMIT_*·설치 항목 제외. 설정 페이지에서 관리 항목 값 변경 409, 사용량 키 생성 잠금, "HAL 관리" 카드.
• 두 모듈 package.json 에 ariwebSuite.halCompat = "0.4.0". 파일이 없으면 동작 변화 없음(단독 운영).

6. 화면·AI

• 운영자 콘솔 /ops/settings "통합 설정": 모듈 탭 → 범위(전체/서버) → 묶음별 입력 → 저장 → "서버에 적용"(서버 선택·재시작) → 서버별 적용 상태. 운영 현황 서버 카드에 "설정 적용 필요".
• AI 도구: hal_settings_get(읽기) · hal_settings_set(고위험, 비밀값 거부 secret_not_allowed) · hal_settings_apply(고위험).

7. 알려진 제한

• HAL 에서 지정을 지워도 모듈에 이미 적용된 값은 그대로 남는다(잠금만 풀린다). 되돌리려면 HAL 에서 원하는 값을 지정해 다시 적용한다.
• Webmaker 의 등급·내부 호출 모델은 그 서버에서 "사용 가능"인 모델만 저장된다 — 아니면 module_apply_failed 로 보고된다.