33 lines
6.6 KiB
Markdown
33 lines
6.6 KiB
Markdown
|
# Ariweb Suite 개발 지시 — 작성자: Oz · v0.4.0
|
||
|
|
|
||
|
|
**작성자:** Oz
|
||
|
|
**작성일:** 2026-10-29
|
||
|
|
**이전 버전:** v0.3.17(HawkEye·통합 배포, Oz) · v0.3.10 · v0.3.9 · v0.3.2 · v0.3.1 · v0.3.0 · v0.2.1 · v0.2.0 · v0.1.4 · v0.1.1
|
||
|
|
**이번 개정:** 도입 모듈 관리 콘솔의 서버 단위 설정 권한을 HAL 로 이전(통합 설정 관제). HAL 0.3.17 → **0.4.0**. Webmaker 1.8.0 → **1.9.0**, AriMail 1.0.11 → **1.1.0**(각각 "HAL 0.4.0 대응" 명시). 이전 지시의 모든 기준은 그대로다.
|
||
|
|
|
||
|
|
## 1. 사용자 요구(Oz 원문, 약화 금지)
|
||
|
|
1. **Webmaker 관리 콘솔의 권한 이전.** HAL 에서 각 Webmaker 의 시스템 콘솔 주요 기능을 통합 관제한다: API 키 관리 · 마진·가격 정책 관리 · 모델 등 주요 설정 관리 · 기타 전체 적용 서비스 · 개별 서버 설정. 통합 인터페이스를 새로 만들고, HAL 에서 배포된 모든 서버를 관리할 수 있게 한다.
|
||
|
|
2. **AriMail 관리 콘솔의 통합 관리.** 도메인별 관리를 제외한 서버 단위 관리는 HAL 에서 통합 관리한다. 개별 메일 서버(도메인) 관리는 메일 서버 사용자가 직접 한다.
|
||
|
|
3. **기타 서비스 서버의 설정 통합 관리.** 그 밖의 서버(Node Agent·백업·HawkEye 등) 설정도 HAL 에서 통합 관리한다.
|
||
|
|
4. 필요한 모듈(Arimail·Webmaker·backup 등)을 모두 업그레이드한다. 각 모듈의 중간 버전을 1 올리고, 각 모듈이 **HAL 0.4.0 대응 버전**임을 명시한다. 이번 릴리스는 **HAL 0.4.0**.
|
||
|
|
|
||
|
|
## 2. 필수 동작(계약)
|
||
|
|
1. **설정 목록(catalog)** `hal/settings/catalog.mjs`: 모듈별(webmaker·arimail·agent) 관리 항목을 묶음(group)으로 선언한다 — Webmaker: `API 키·인증`(auth.mode·auth.apiKey·auth.oauthToken·serviceApiKey·backlogKey·mail.apiKey·source.token·ariweb.secret·mail.adminPassword) · `마진·가격 정책`(marginPct·fx.*·signupCredit·maxEdits·defaultTier·tiers.*·signupApproval) · `모델`(internalRef·defaultModel·claudeModels·ai.claudeMaxTurns·ai.openaiMaxTurns·ai.maxJobMinutes·ai.maxConcurrentJobs·ai.codexSandbox) · `전체 적용 서비스`(service.allowSignup·letsEncryptEmail·mail.fromName·mail.defaultDomain·ariweb.portalUrl·endpoints.*·limits.*) · `서버별 설정`(service.publicBaseUrl·service.siteOrigin·service.trustedProxies·service.internalAllow·ai.claudeBin·ai.codexBin·source.*·mail.url·mail.apiUrl·mail.domain·mail.adminLogin·mail.nickname·mail.ip). AriMail: 서버 단위 항목(수·발신 방식, Resend, DNS 제공자, SMTP 중계, Haraka, 사이트 표시, 사용량 API, Ariweb SSO) — 도메인별 `LIMIT_*` 는 제외. Agent: heartbeatMs. 항목마다 형식(text·int·number·bool·enum·list·url·secret)·범위·재시작 필요 여부·범위(global/server).
|
||
|
|
2. **저장소** `managed_settings`(scope `global` | `server:<id>`, module, key, value_json): 비밀값은 행에 두지 않고 Vault(`managed:<scope>:<module>:<key>`)에만 두며 행에는 참조만. 유효값 = 기본값 ← 전체(global) ← 서버 덮어쓰기(server). `managed_settings_state`(server_id, module, applied_hash, applied_at, status, error, job_id)에 서버별 적용 상태.
|
||
|
|
3. **운영자 API**(`/ops/api/settings`): 목록·조회(GET, 비밀값은 "있음/없음"만) · 저장(PUT, 재인증 필요 — 가격·키·모델은 고객 영향) · 삭제(DELETE, 재인증) · 적용(POST `/:module/apply`, 재인증; 대상 비우면 그 모듈이 배치된 서버 전체, 없으면 즉시 `no_targets`). 알 수 없는 항목·형식 오류는 400 `bad_setting`. 감사 기록에 값은 남기지 않고 키 이름만.
|
||
|
|
4. **적용 작업** `settings.apply`(부모) → `settings.apply.target`(서버별) → Agent 작업 `module.configure`: Agent 가 HAL 에서(`GET /agent/v1/settings/:module`, Agent HMAC 인증, 자기 서버 범위의 유효값·비밀값) 설정을 받아 모듈 데이터 디렉터리의 `hal-managed.json`(0600, 실행 계정이 다르면 그 계정으로)으로 쓰고, 요청 시 서비스를 재시작한 뒤 건강을 확인한다. 결과의 hash 가 HAL 이 계산한 hash 와 같아야 `ok`. 다른 서버의 설정은 받을 수 없다.
|
||
|
|
5. **모듈 대응**: Webmaker 1.9.0 `lib/hal-managed.js` — 기동 때 `hal-managed.json` 을 읽어 settings·config·vault 에 적용하고(같은 hash 면 생략), 관리 항목은 관리자 콘솔 API 에서 409 `managed_by_hal` 로 잠그며 화면에 "HAL 관리" 표시. AriMail 1.1.0 `server/hal-managed.mjs` — 기동 때 설정 파일에 적용(hidden 항목 포함), 설정 API 에서 관리 항목 409 `managed_by_hal`, 화면 표시. 두 모듈 모두 package.json 에 `ariwebSuite.halCompat = "0.4.0"` 을 명시하고 CHANGELOG 에 적는다. Agent 0.4.0: `module.configure` 작업, 자기 설정(heartbeatMs)도 `hal-managed.json` 으로 받는다.
|
||
|
|
6. **운영자 화면** `/ops/settings` "통합 설정 관제": 모듈 탭 → 범위(전체 / 서버 라디오) → 묶음별 입력(비밀값은 있음/없음·새 값 입력만) → 저장 → "서버에 적용"(체크 선택·재시작 여부) → 서버별 적용 상태(hash·시각·오류). 운영 현황에 "적용 안 된 설정" 수.
|
||
|
|
7. **AI 도구**: `hal_settings_get`(읽기) · `hal_settings_set`(고위험, 비밀값은 받지 않음) · `hal_settings_apply`(고위험). 스킬 문서에 설명.
|
||
|
|
8. 도입 모듈은 참조 저장소(WebHosting_AI_agent `release/1.9.0`, AriMail `release/1.1.0`)에 같은 변경을 커밋·push 하고, `scripts/import-sources.mjs` 의 고정 커밋을 새 커밋으로 갱신해 다시 들여온다(Suite 전용 수정 파일은 보존).
|
||
|
|
|
||
|
|
## 3. TDD·검증
|
||
|
|
- `test/hal-040.test.mjs` 를 먼저 쓰고 RED 확인 뒤 구현(카탈로그·저장/조회/유효값/비밀값 Vault·API 권한·적용 작업→Agent→상태·Agent 설정 API 범위·화면·AI 도구·버전·문서). `test/agent.test.mjs` 에 `module.configure`. 모듈 저장소에 `test/hal-managed.test.*`. 기존 테스트·전체 Suite(버전 0.4.0).
|
||
|
|
- 배포 뒤 bear read-back(마이그레이션·설정 API·화면), 이어서 HAL 작업으로 agent 0.4.0 → webmaker 1.9.0 → arimail 1.1.0 을 대상 서버에 순서대로 배포하고 건강을 확인한다(실패 시 중단·되돌리기).
|
||
|
|
|
||
|
|
## 4. 버전·배포
|
||
|
|
- HAL 0.4.0: package.json·README·VERSION_HISTORY·개발 지시·docs. 커밋 → push → main 병합 → 깨끗한 main 빌드·verify → bear HAL 배포 → read-back → HAL 로 나머지 모듈 배포.
|
||
|
|
|
||
|
|
## 5. 완료 조건
|
||
|
|
변경 파일, RED/GREEN·전체 테스트, 모듈 저장소 커밋·고정 커밋, 커밋·병합 커밋, artifact sha256, 배포 read-back, 모듈 배포 결과, 운영자 조치, 알려진 제한을 보고한다.
|