어시스턴트
관리 콘솔 안의 운영 어시스턴트입니다. 값은 한 문장에 있습니다 — 지금 뭐가 문제고, 왜 그렇고, 뭘 하면 되나. 이 노드에 대해 말로 물으면 콘솔이 이미 내주는 API 를 읽어 답하고, 할 일이 있으면 승인 카드로 내놓습니다. 카드를 사람이 승인하기 전에는 아무것도 실행되지 않습니다.
| 항목 | 값 |
|---|---|
| 여는 곳 | 레일의 어시스턴트 아이콘 — 주소는 https://<서버IP>:4950/assistant/ |
| 필요한 것 | OpenAI 호환 LLM 게이트웨이 하나. 콘솔에 들어 있지 않으므로 직접 연결합니다 — 게이트웨이 설정 |
| 답의 재료 | 이 노드의 콘솔 API 읽기 도구 14개 |
| 실행 | 허용된 동작 7개의 승인 카드뿐 |
| 범위 | 콘솔을 연 그 노드 하나 |
화면 구성
왼쪽이 대화이고, 오른쪽 칼럼에 위에서부터 셋이 놓입니다.
| 자리 | 이름 | 하는 일 |
|---|---|---|
| 왼쪽 | 대화 | 질문을 적고 답을 읽습니다. Enter 가 [묻기], Shift+Enter 가 줄바꿈입니다. 답에서 나온 승인 카드도 여기에 함께 나옵니다 |
| 오른쪽 위 | 게이트웨이 | 평소에는 한 줄 요약으로 접혀 있습니다. 쓸 수 없는 상태가 측정되면 저절로 펼쳐집니다 |
| 오른쪽 가운데 | 열린 제안 | 결정을 기다리는 카드 전부입니다. 대화에서 나왔든 알람에서 나왔든 여기 모이고, 10초마다 다시 읽습니다 |
| 오른쪽 아래 | 이 답이 읽은 것 | 마지막 답이 부른 API 호출을 순서대로 보여 줍니다 |
지금 뭐가 문제인가
노드의 상태 · 버전 · 알람 · 백업을 말로 묻습니다. 어시스턴트는 질문마다 다시 읽고 답합니다 — 앞선 답은 낡은 것으로 치고 근거로 쓰지 않습니다. 무엇이 WARN · FAIL 인지는 콘솔의 판정을 그대로 전하고, 원시 수치에 자기 기준을 들이대지 않습니다. 측정하지 못한 것은 못 쟀다고 말합니다.
이렇게 묻습니다.
- 지금 이상이 있는 컴포넌트가 있나?
- 지금 올라와 있는 알람은 뭐고, 음소거된 것이 있나?
- 워커가 전부 링에 들어와 있나?
- WAL 과 복제 슬롯 상태는 어떤가?
- 뒤처진 Kafka 컨슈머 그룹이 있나?
- 최근 한 시간 동안 이 노드에서 무슨 일이 있었나?
- 마지막 백업은 언제 끝났고, 지금 도는 백업이 있나?
- 누가 최근에 무엇을 재시작했나?
- 이 노드의 버전과 가동 시간은?
- 이 릴리스에 들어 있는 Kafka 버전은?
system 도구는 이 노드의 정체 · 버전 · 가동 시간을 읽고, component_versions 도구는 이 릴리스가 싣고 나온 구성요소 표를 읽습니다. 뒤의 것은 지금 노드에서 도는 것을 잰 값이 아닙니다.
측정 결과는 다음 왕복에 전부 실려 갑니다. 「전부 점검해 줘」보다 컴포넌트나 화면 이름을 대고 묻는 쪽이 빠르고, 답이 끝까지 올 가능성도 큽니다.
왜 그런가
이유를 물으면 어시스턴트는 헬스 · 알람 · 최근 작업 · 로그 목록을 함께 읽고, 이 순서로 답합니다 — 무엇이 잘못됐나(콘솔의 판정) → 왜(유력한 후보부터, 읽은 필드를 대며) → 뭘 하면 되나(카드 또는 구체적인 다음 단계).
서버가 판정 곁에 두 가지를 붙여 줍니다. 최근 30분 안의 작업과 지금 도는 작업 — 「방금 누가 재시작했다」가 이유인 경우가 많기 때문입니다. 그리고 문제 행의 실제 로그 파일 이름입니다.
- 왜 cassandra 가 빨간가?
- 이 알람의 원인 후보를 꼽아 줘.
- kafka 가 FAIL 인데 무엇부터 확인해야 하나?
콘솔 문서가 원인을 직접 적어 둔 경우가 아니면 어시스턴트는 하나를 사실로 단정하지 않습니다. 읽은 것 중에 가리키는 것이 없으면 원인을 모른다고 답합니다. 답은 판단의 재료이지 진단 결과가 아닙니다. 아래 이 답이 읽은 것으로 검산하세요.
로그 본문은 읽지 못합니다. 로그 도구는 어떤 파일이 있고 언제 마지막으로 쓰였는지만 답합니다. 그래서 어시스턴트는 로그에 무엇이 적혔다고 말할 수 없고, 열어 볼 파일을 이름 그대로 짚어 로그 화면으로 보냅니다.
답을 검산한다 — 이 답이 읽은 것
답은 근거와 함께 옵니다. 오른쪽 이 답이 읽은 것이 마지막 답이 부른 API 호출을 부른 순서대로 싣고, 각 줄의 [화면 열기] 가 같은 사실을 손으로 볼 수 있는 화면으로 갑니다. 어느 화면으로 갈지는 서버가 정합니다.
답 머리의 도구 호출 N회차 는 왕복 수입니다. 서버가 판정 곁에 붙이려고 읽은 작업 · 로그 목록도, 내용이 실제로 붙었으면 패널에 줄로 남습니다. 패널에 「마지막 답은 아무것도 부르지 않았다 — 질문만으로 적은 답이다.」 가 나오면, 그 답은 이 노드를 재지 않은 답입니다.
서버가 답을 검사한다
모델의 답은 나가기 전에 이번 질문에서 실제로 일어난 일과 대조됩니다. 어긋나면 한 번 되돌려 다시 쓰게 하고, 그래도 어긋나면 그 문장을 지운 뒤 답 아래에 표시를 답니다.
| 답 아래의 표시 | 무엇을 막았나 | 할 일 |
|---|---|---|
| 「이번 답은 읽은 근거가 없다 — 이 노드에서 아무것도 읽지 않았으므로 측정값으로 읽지 마라. …」 | 아무것도 읽지 않은 답. 측정값처럼 보이는 내용이 있으면 답 전체를 지웁니다 | 무엇을 읽을지 말해 다시 묻습니다 |
| 「카드를 만들지 못했다. 어시스턴트가 제안했다고 썼지만 그런 카드가 없어 그 문장을 지웠다. …」 | 없는 카드를 만들었다는 주장 | 다시 요청하거나 해당 화면을 씁니다 |
| 「이번에 읽은 어디에도 없는 버전·날짜를 답에서 지웠다. …」 | 이번에 읽지 않은 값 — 버전 · 날짜 · 세 자리 이상의 숫자 · FAIL · WARN | 근거 패널의 화면에서 확인합니다 |
| 「아래 항목을 읽었지만 결론을 쓰지 못했다. …」 | 왕복을 다 쓰고도 결론이 없는 답 | 그 화면을 열거나 컴포넌트 하나를 짚어 묻습니다 |
카드의 어시스턴트의 판단도 같은 검사를 거칩니다. 다만 이 검사는 모양을 보는 것이지 뜻을 검증하는 것이 아닙니다. 표시가 없다고 답이 맞다는 뜻은 아닙니다.
읽기 도구 14개
어시스턴트가 읽을 수 있는 것은 아래가 전부입니다. 모두 GET 이고 아무것도 바꾸지 않으며, 여기 없는 엔드포인트에는 어떤 인자로도 닿지 못합니다.
| 도구 | 읽는 곳 | 무엇을 | 근거 링크가 가는 화면 |
|---|---|---|---|
health | /api/health | 컴포넌트별 판정 | 상태 및 정보 |
services | /api/services | 서비스 목록 · 기동 여부 · 포트 | 상태 및 정보 |
alarms | /api/alarms | 올라온 알람 · 연속 불량 횟수 · 음소거 · 알리지 못한 사유 | 알람 |
workers | /api/workers | 워커의 링 합류 여부와 용량 | 워커 |
jobs | /api/jobs | 최근 작업(재시작 · 렌더 · 백업 · 진단) — 누가 무엇을 언제 돌렸고 끝났는가, 지금 도는 작업 | 작업 |
storage | /api/storage | 볼륨 · WAL · 복제 슬롯 · 저장소 크기 | 스토리지 |
backup | /api/backup | 백업 이력 — 엔진 · 종류 · 상태 · 끝난 시각 · 크기, 지금 도는 백업 | 백업 |
events | /api/events | 이 노드의 사건 타임라인 | 이벤트 |
flow | /api/flow | Kafka 컨슈머 그룹별 랙 | 토폴로지 |
logs | /api/logs | 로그 파일 목록과 최근 기록 시각 — 본문이 아닙니다 | 로그 |
doctor | /api/doctor | 진단 결과 — 통과 · 실패 · 못 잼 | 진단 |
system | /api/system | 이 노드의 정체 · 버전 · 가동 시간 · 힙 | 상태 및 정보 |
component_versions | /api/component-versions | 릴리스의 구성요소 표 — 공식 버전 · 자체 버전 · 포트 · 라이선스 · 출처 | 상태 및 정보 |
service_impact | /api/services/{name}/impact | 이 서비스를 멈추면 무엇이 같이 멈추나 | 상태 및 정보 |
일부러 뺀 것 — 시크릿, 렌더된 설정, 로그 본문 · 검색 · 스트림. 앞의 둘에는 자격증명이 실려 있고, 로그 본문은 자격증명이 섞여 있을 가능성이 가장 큰 자유 텍스트입니다.
도구 응답은 그대로 가지 않습니다. 헬스 · 알람 · 작업 · 백업 · 로그 · 진단 · 서비스 · 버전 문서는 필요한 필드만 추려 문제 행을 앞에 두고 시각을 풀어 적은 뒤 모델에게 가고, 어느 도구든 도구당 4,000자에서 자릅니다. 잘렸으면 모델도 잘린 것을 알고, 답이 거기에 달렸으면 그렇다고 말하고 화면을 가리키도록 돼 있습니다.
뭘 하면 되나 — 승인 카드
할 수 있는 일이 있으면 어시스턴트는 실행하지 않고 카드를 올립니다. 사람이 화면을 봐야 할 일이면 카드 없이 어느 화면을 볼지 답합니다. 직접 요청해도 됩니다.
- 진단을 돌리는 카드를 올려 줘.
- cassandra 전체 백업 카드를 올려 줘.
- 이 알람 소리를 끄는 카드를 올려 줘.
허용된 동작 7개
카드가 부를 수 있는 것은 이 일곱이 전부입니다. 목록 밖의 동작은 카드가 만들어지는 시점에 거절되고, 화면에 나타나지도 않습니다.
| 동작 | 부르는 곳 | 대상 | 카드 전에 서버가 재는 것 |
|---|---|---|---|
설정 렌더 (CONFIG_RENDER) | POST /api/config/render | 없음 | 재지 않습니다 — 렌더된 파일을 어느 서비스가 읽는지 콘솔이 따지지 않습니다 |
서비스 재시작 (SERVICE_RESTART) | POST /api/services/{name}/restart | 서비스 하나 | 같이 멈추는 것 |
설정 렌더 + 재시작 (CONFIG_RENDER_RESTART) | 위 둘을 차례로 | 서비스 하나 | 같이 멈추는 것, 도는 작업이 없는지 |
백업 실행 (BACKUP_RUN) | POST /api/backup/run | postgres-full · postgres-diff · cassandra-full · cassandra-diff 중 하나 | 도는 백업이 없는지 |
진단 실행 (DOCTOR_RUN) | POST /api/doctor/run | 없음 | 없음 — 읽기만 합니다 |
알람 소리 끄기 (ALARM_MUTE) | POST /api/alarms/{name}/mute | 알람 컴포넌트 하나 | 그 알람이 올라와 있고 소리가 나는지 |
알람 소리 다시 켜기 (ALARM_UNMUTE) | POST /api/alarms/{name}/unmute | 알람 컴포넌트 하나 | 그 알람이 올라와 있고 음소거 상태인지 |
전부 그 화면의 버튼이 이미 부르는 엔드포인트입니다. 어시스턴트 전용 실행 경로가 없으므로 승인으로 새로 할 수 있게 되는 일은 없고, 작업 락 · 이력 · 감사 기록도 버튼을 눌렀을 때와 같습니다.
카드가 지나는 길
- 서버가 잰다. 어시스턴트가 동작을 고르면 콘솔이 위 표의 전제를 직접 읽습니다. 영향 범위는 모델이 쓰지 않습니다 — 서비스의 선언된 기동 순서에서 읽습니다. 재야 하는 것을 못 재면 카드를 만들지 않습니다.
- 사람이 승인한다. 카드를 읽고 [승인] 또는 [거절] 을 누릅니다. 누르기 전에는 아무 일도 없습니다.
- 승인 때 다시 잰다. 재야 하는 동작이면 다시 읽고, 영향 범위가 카드와 달라졌으면 실행을 거절하며 그때와 지금을 함께 보여 줍니다. 전제가 깨졌을 때도 같습니다.
- 30분이면 만료된다. 판단은 한 순간에 대한 것입니다. 시간이 지난 카드에는 승인 버튼이 없습니다. 필요하면 다시 물어 새 카드를 받습니다.
- 한 번만 실행된다. 결정된 카드는 다시 승인되지 않습니다. 같은 카드를 두 번 눌러도 두 번 돌지 않습니다.
CONFIG_RENDER 와 DOCTOR_RUN 은 카드 전에 재는 것이 없으므로 3단계에서 다시 재는 것도 없습니다.
카드 읽는 법
카드 머리에 출처(대화에서 / 알람에서), 올라온 시각, 어시스턴트의 판단이 있습니다. 판단은 모델의 글이고 틀릴 수 있습니다. 이번에 읽지 않은 값이 든 문장은 서버가 지웁니다. 그 아래는 이 순서로 고정돼 있습니다.
| 순서 | 카드의 제목 | 내용 |
|---|---|---|
| 1 | 무엇이 같이 멈추나 | 콘솔이 잰 것 — 모델이 쓴 글이 아닙니다. 설정 렌더 카드에는 잰 값 대신 「재지 않았다.」 가 나옵니다. 음소거 카드에서는 어느 알람이 조용해지나, 해제 카드에서는 어느 알람이 다시 울리나 |
| 2 | 되돌릴 수 있나 | 동작별 안내 |
| 3 | 정확히 무엇을 부르나 | 호출할 메서드와 경로. 렌더 + 재시작은 두 단계가 차례로 나옵니다 |
| 4 | 하지 «않는» 것 | 그 동작이 건드리지 않는 것 |
| 5 | 승인을 누르기 전에 · [승인] · [거절] | 승인할 수 있는 카드에만 나옵니다 |
대화에서 나온 카드에는 읽은 것도 함께 나옵니다. 카드를 만들기 전에 실제로 답한 읽기 도구이고, 각각 그 화면으로 링크됩니다.
같이 멈추는 것은 찾지 못했다. 와 못 쟀다 — 아무도 따져 보지 않았다. 는 다른 말입니다. 서버는 재야 할 영향을 못 쟀으면 카드를 아예 만들지 않지만, 카드에 「못 쟀다」가 보이면 승인하지 마세요.
설정 렌더 카드의 「재지 않았다.」 는 다릅니다. 이 단계가 멈추는 것은 없고, 도는 서비스는 바뀐 파일을 다음 기동 때 읽습니다. 다만 그 다음 재시작이 무엇을 바꿀지는 아무도 재지 않았습니다.
렌더가 실패하면 재시작하지 않습니다. 렌더가 끝나고 재시작이 실패하면 새 설정은 노드에 있고 서비스는 아직 옛 설정으로 돕니다. 어디까지 갔는지는 카드의 서버가 한 말에 적힙니다. 이 동작은 렌더가 끝나기를 기다리므로 승인 뒤 몇 분이 걸릴 수 있습니다. 콘솔이 먼저 기다리기를 멈췄다면 다시 누르기 전에 카드 상태와 작업 화면을 확인하세요.
카드 상태
| 화면 문구 | 뜻 |
|---|---|
| 결정을 기다리는 중이다 | 열린 제안에 있습니다 |
| 승인돼 실행됐다 | 요청이 받아들여졌고 따라갈 작업이 없습니다. 호출 결과가 서버가 한 말에 붙습니다 |
| 승인돼 시작됐다. 작업은 아직 도는 중이다 | 작업을 띄우는 동작입니다. 시작이지 결과가 아닙니다. 카드가 3초마다 작업을 따라 읽습니다 |
| 승인돼 작업이 성공으로 끝났다 | 작업이 성공했습니다 |
| 승인됐으나 작업이 실패했다 — 작업 화면을 봐라 | 호출은 받아들여졌고 작업이 실패했습니다 |
| 승인돼 시작됐다. 결과를 읽지 못했다 — 작업 화면을 봐라 | 시작은 됐고 결과를 모릅니다. 실패로 읽지 마세요 |
| 승인됐는데 실행이 실패했다 | 승인은 됐고 호출이 실패했습니다. 사유가 서버가 한 말에 붙습니다 |
| 거절됐다 | 아무것도 부르지 않았습니다 |
| 아무도 결정하지 않은 채 만료됐다 | 30분이 지났습니다 |
승인할 수 없는 카드에는 흐린 버튼 대신 「여기서 결정할 것이 없다:」 와 위 상태가 나옵니다.
카드가 안 만들어지거나 실행이 거절될 때
서버의 거절은 숨겨지지 않습니다. 대화에서는 어시스턴트가 사유를 전하고, 승인 때의 거절은 카드에 실행되지 않았다. 뒤에 서버의 영어 문장 그대로 붙습니다.
| 상황 | 언제 | 어떻게 하나 |
|---|---|---|
| 영향을 못 읽음 | 카드 전 · 승인 때 | 서비스 이름과 상태 및 정보 화면을 확인 |
영향 범위가 바뀜 (has CHANGED) | 승인 때 | 다시 물어 새 카드를 받는다 |
| 백업이나 복구가 도는 중 | 카드 전 · 승인 때 | 끝난 뒤 다시 묻는다 |
| 다른 작업이 도는 중 (렌더 + 재시작) | 카드 전 · 승인 때 | 끝난 뒤 다시 묻는다 |
| 그 알람이 없음 · 이미 음소거 · 음소거 아님 | 카드 전 · 승인 때 | 알람 화면으로 상태 확인 |
| 대상이 콘솔 자신 | 카드 전 · 승인 때 | 콘솔은 자기를 재시작하지 못합니다. 호스트에서 pd 로 |
| 이미 결정됐거나 실행 중인 카드를 승인 · 거절 | 승인 · 거절 때 | 거절은 결정을 기다리는 카드에만 됩니다. 카드 상태를 확인합니다 |
| 이 노드에 제안 저장소가 없음 | 카드 전 | 적어 두지 못한 카드는 두 번 승인될 수 있어 만들지 않습니다 |
열린 제안에 「이 노드는 승인을 실행할 수 없다 — 승인해도 여기 있는 것은 돌지 않는다.」 가 나오면 이 노드의 저장소가 준비되지 않은 것입니다.
알람에서 올라오는 카드
아무도 묻지 않아도 카드가 올라올 수 있습니다. 알람이 올라가는 순간 콘솔이 게이트웨이에 한 번 묻고, 할 일이 있으면 열린 제안에 카드를 올립니다. 출처는 알람에서 로 표시되고, 답하는 사람이 없는 경로이므로 도구 왕복 없이 알람과 서비스 목록만 실어 보냅니다.
- 고를 수 있는 동작은 서비스 재시작과 설정 렌더 둘뿐입니다. 백업 · 진단 · 음소거 · 렌더 + 재시작은 대화에서만 나옵니다.
- 이 경로의 제목과 판단은 영어로 적힙니다. 타임라인이 영어이기 때문입니다.
- 재시작의 대상은 모델이 아니라 콘솔이 정합니다. 헬스 문서에서 그 알람 컴포넌트를 돌리는 서비스를 찾아 씁니다.
- 알람 화면의 규칙이 그대로 적용됩니다 — 규칙이 꺼져 있거나, 최소 심각도에 못 미치거나, 억제 창 안이면 묻지 않습니다.
- 같은 동작 · 같은 대상의 카드가 이미 열려 있으면 또 만들지 않습니다.
- 알람이 내려가면 그 카드는 거둬집니다. 콘솔이 재기동한 뒤에는 거두지 못하고, 그때는 30분에 만료됩니다.
- 열린 제안에는 결정을 기다리는 카드만 있으므로, 승인한 카드는 목록에서 빠집니다. 알람 카드를 승인한 뒤의 결과는 작업 화면에서 봅니다.
- 무슨 일이 있었는지는 이벤트 타임라인에 남습니다 — 카드를 올렸다, 제안할 것이 없었다, 게이트웨이에 묻지 못했다, 카드가 거절됐다.
게이트웨이가 켜져 있어야 하고, 제안 저장소가 준비돼 있어야 하며, PP_DATALAKE_ADMIN_API_KEY 가 설정돼 있어야 합니다 — 로그인한 사람이 없을 때 콘솔이 자기 API 를 읽는 신원이 그 키입니다. 빠진 것이 있으면 사유가 로그에 한 번 남습니다. 알람과 통지는 이와 무관하게 그대로 동작합니다.
할 수 없는 것
아래는 카드로도 나오지 않습니다. 허용 목록에 없으므로 모델이 요청해도 거절됩니다.
| 안 되는 것 | 어디서 하나 |
|---|---|
| 복구 | 백업 화면 — 대상을 다시 적게 하는 절차가 그쪽에 있습니다 |
| 데이터 삭제 | 어시스턴트로는 할 수 없습니다 |
| 시크릿 조회 · 변경 | 어시스턴트는 자격증명을 읽지 못합니다. 각 컴포넌트 상세의 자격증명 카드에서 |
| 노드 제거 | 워커 화면이 보여 주는 명령을 호스트에서 |
| 백업 스케줄 변경 · 스케줄 실행 | 어시스턴트로는 할 수 없습니다. 스케줄 편집은 백업 화면 |
| 작업 취소 | 어시스턴트로는 할 수 없습니다 |
| 서비스 기동 · 정지 | 카드로는 재시작만 나옵니다. 정지는 반쯤 적용되면 노드를 더 나쁘게 남깁니다 |
| 업그레이드 | 업그레이드 화면 |
대화는 어디에 남나
대화는 그 브라우저 탭의 sessionStorage 에만 있습니다. 화면도 그렇게 말합니다 — 「이 전사는 이 브라우저 탭 안에만 있다. 새로고침해도 남고, 탭을 닫거나 로그아웃하면 사라진다. 노드는 한 줄도 저장하지 않으므로 남길 것이 있으면 복사해 둬라.」
- 새로고침해도 남습니다. 탭을 닫거나 로그아웃하면 사라집니다. 다른 탭에서는 보이지 않습니다.
- 탭에는 최근 40개 항목까지만 둡니다. [지우기] 로 직접 비울 수 있습니다.
- 질문할 때 탭이 앞선 대화를 함께 보내고, 서버는 그중 최근 20개 메시지를 읽습니다. 맥락일 뿐 근거로 쓰지 않습니다.
- 카드는 대화가 아닙니다. 카드는 탭에 복사되지 않고 언제나 서버에서 읽습니다. 제목 · 판단 · 영향 · 결정한 사람 · 결과가 노드의 PostgreSQL 에 7일 남습니다(기동 때 정리). 승인으로 실행된 호출은 감사 화면에 남습니다.
노드는 대화를 저장하지 않지만, 답을 만들려면 질문 · 앞선 대화 · 추린 도구 응답을 게이트웨이로 보냅니다. 알람 카드는 알람 · 알람 목록 · 서비스 목록을 보냅니다. 노드의 상태 정보가 그 게이트웨이까지 간다는 뜻이므로, 사내 정책에 맞는 게이트웨이를 연결하세요.
권한
이 콘솔에는 계정이 하나이고 역할이 없습니다. 로그인 세션이 있으면 질문도, 승인도, 게이트웨이 설정도 할 수 있습니다.
| 하는 일 | 필요한 것 |
|---|---|
| 질문 | 로그인 세션 |
| 승인 · 거절 | 로그인 세션 |
| 게이트웨이 저장 · 확인 | 로그인 세션 |
| 제안 목록 · 게이트웨이 설정 읽기 | 로그인 세션 또는 콘솔 API 키 |
- 질문한 사람과 승인하는 사람이 달라도 되고, 같아도 됩니다. 두 사람 승인 절차는 없습니다. 탭의 대화는 그 탭의 것이지만 카드는 노드의 것이라, 열린 제안은 로그인한 누구에게나 같이 보입니다.
- API 키로는 묻거나 승인할 수 없습니다. 이 동작들은 세션을 요구합니다.
- 어시스턴트의 측정과 승인된 호출은 그 사람의 세션으로 나갑니다. 권한이 늘어나는 경로가 없습니다.
- 카드의 결정자와 감사 기록에는 세션의 로그인 이름이 적힙니다. 계정을 나눠 쓰면 사람을 가려내지 못합니다.
게이트웨이 설정
어시스턴트는 OpenAI 호환 게이트웨이(GET /v1/models, POST /v1/chat/completions)를 부릅니다. 콘솔에는 기본 주소가 없습니다 — 현장의 망에서 닿는 곳을 직접 넣습니다. 설정은 화면에서 저장되고 노드의 PostgreSQL 에 들어가며, 설정할 환경변수는 없습니다.
오른쪽 칼럼 맨 위의 [게이트웨이 설정 펼치기] 를 누릅니다. 게이트웨이는 하나뿐이라 고를 이름이 없고, 칸은 넷입니다.
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 오른쪽 맨 위 | 접힌 한 줄 요약 — 누르면 펼쳐집니다 |
| ② | 엔드포인트 | 게이트웨이 기준 URL |
| ③ | 키 | 저장 여부와 끝 네 자리만 보입니다 |
| ④ | 모델 | 게이트웨이가 답한 목록에서 고릅니다 |
| ⑤ | 이 게이트웨이를 쓴다 · [저장] | 저장해야 적용됩니다 |
| ⑥ | 확인 | [연결 확인] — 아래 |
| 칸 | 넣는 것 |
|---|---|
| 엔드포인트 | 게이트웨이의 기준 URL. 필수. http:// 또는 https:// 로 시작해야 하고, 끝에 /v1 이 있든 없든 같습니다 |
| 키 | 선택. 신뢰망의 게이트웨이는 키가 없어도 됩니다. 비워 두면 저장된 키가 그대로 남습니다. 화면에는 저장 여부와 끝 네 자리만 나오고 값은 나오지 않습니다 |
| 모델 | 목록에서 고릅니다. 게이트웨이가 답한 이름만 나오고 자유 입력 칸은 없습니다 |
| 이 게이트웨이를 쓴다 | 끄면 콘솔이 아무것도 묻지 않고 알람 카드도 만들지 않습니다. 저장해야 적용됩니다 |
처음 연결하는 순서입니다.
- 엔드포인트와 키를 적고 [저장] 합니다. 확인은 적어 넣은 값이 아니라 저장된 값으로 접속합니다.
- [연결 확인] 을 누릅니다. 주소 · TLS · 키 · 모델 목록을 한 번에 확인합니다.
- 모델을 고르고 다시 [저장] 합니다. 대화가 열립니다.
- [도구 호출 시험] 을 한 번 돌립니다. 모델이 도구를 설명만 하지 않고 실제로 부르는지 봅니다. 통과하지 못해도 질문은 되지만, 그 모델로는 답의 근거를 읽지 못하고 카드도 만들어지지 않습니다.
게이트웨이와 모델이 저장돼 있으면 [연결 확인] 은 화면을 열 때마다 콘솔이 스스로 한 번 돌립니다. 그래서 화면을 연 직후 잠깐 「지금 이 게이트웨이를 확인하는 중」 이 보이고, 통과하면 대화가 열립니다. [도구 호출 시험] 은 실제 모델 호출이라 자동으로 돌지 않습니다.
설정이 안 됐을 때
대화가 열리지 않으면 입력칸 자리에 아직 적어 넣을 칸이 없다 와 사유가 나옵니다. 흐린 입력칸은 없습니다.
| 오른쪽 요약 | 뜻 | 할 일 |
|---|---|---|
| 저장된 게이트웨이 없음 | 엔드포인트가 저장되지 않았습니다 | 엔드포인트를 적고 저장 |
| 고른 모델 없음 | 게이트웨이는 있고 모델이 없습니다 | 연결 확인 → 모델 선택 → 저장 |
| 게이트웨이가 꺼져 있다 | 저장된 설정이 꺼진 상태입니다 | 이 게이트웨이를 쓴다를 켜고 저장 |
| 폼에 저장되지 않은 변경이 있다 | 질문은 저장된 게이트웨이로 갑니다 | 저장 |
| 저장돼 있지만 이 탭에서 확인한 적이 없다 | 콘솔이 답하는지 말할 수 없습니다 | 연결 확인 |
| 지금 이 게이트웨이를 확인하는 중 | 자동 확인이 도는 중입니다 | 잠깐 기다립니다 |
| 마지막 확인이 통과하지 못했다 - 사유 | 아래 판정을 봅니다 | 판정별 조치 |
| 게이트웨이 확인됨 - 모델 이름 | 정상 | 대화가 열려 있습니다 |
「이 노드는 어시스턴트 설정을 저장할 수 없다.」 는 이 노드가 데이터레이크 PostgreSQL 에 닿지 못한다는 뜻이고, 그때는 [저장] 을 누를 수 없습니다.
확인 결과 읽는 법
주소와 키가 멀쩡해도 실패하는 경우가 있어 판정이 갈립니다. 맞는 주소를 다시 치기 전에 판정부터 읽으세요. 아래쪽 게이트웨이가 한 말은 번역되지 않은 게이트웨이의 말 그대로입니다. 같은 판정이 대화의 답 자리에도 나옵니다.
| 판정 | 뜻 | 할 일 |
|---|---|---|
| 통과 | 게이트웨이가 답했고 모델 목록을 받았습니다(도구 시험은 모델이 도구를 불렀습니다) | — |
| 확인할 것이 없다 | 저장된 엔드포인트가 없습니다. 통과도 실패도 아닙니다 | 엔드포인트를 적고 저장 |
| 게이트웨이 응답 없음 | 게이트웨이가 주소에서 답하지 않았습니다. 콘솔의 문제가 아니고, 키는 시험되지 않았습니다 | 엔드포인트와, 이 컨테이너에서 그 호스트 · 포트에 닿는지 확인. 방화벽과 타임아웃도 이렇게 보입니다 |
| 키 거부됨 | 주소는 맞고 키가 거절됐습니다 | 새 키를 적고 저장. 비워 두면 거부된 키가 남습니다 |
| 이 모델로는 안 된다 | 엔드포인트도 키도 정상입니다. 고른 모델이 이 요청을 처리하지 않습니다 | 목록에서 다른 모델을 고릅니다 |
| 상류 한도 소진 | 엔드포인트도 키도 정상입니다. 게이트웨이 쪽 상류 계정의 한도가 다했습니다 | 이 화면에서 고칠 것이 없습니다. 한도가 돌아오면 같은 설정으로 통과합니다 |
| 도구를 부르지 않았다 | 모델이 말로만 답했습니다 | 도구 호출을 지원하는 모델을 고릅니다 |
| 게이트웨이 답을 읽지 못했다 | 어느 결과로도 분류되지 않습니다 | 게이트웨이가 한 말을 읽습니다 |
기다림과 끊긴 답
한 질문에 도구를 여러 번 부를 수 있어 답이 늦는 것은 정상입니다. 기다리는 동안 초가 올라가고 [그만 기다리기] 로 멈출 수 있습니다. 질문 하나에 왕복은 8회까지이고, 다 쓰면 더 읽지 않고 그때까지 읽은 것으로 결론을 쓰게 합니다.
| 화면에 나오는 것 | 뜻 | 할 일 |
|---|---|---|
| 「N초 만에 이 질문을 그만뒀다.」 | 직접 멈췄습니다. 바뀐 것은 없습니다 | 다시 묻습니다 |
| 「이 답은 도중에 끊겼다」 | 끝까지 오지 못한 답입니다. 완성된 답으로 읽지 마세요 | 범위를 좁혀 다시 묻습니다 |
| 「콘솔이 200초를 기다리다 그만뒀다.」 | 노드나 게이트웨이의 고장이 아닙니다. 콘솔이 기다리기를 멈췄습니다 | 범위를 좁혀 다시 묻습니다 |
| 「콘솔이 자기 서버에 닿지 못해 아무것도 묻지 못했다.」 | 게이트웨이가 아니라 콘솔 서버 쪽 문제입니다 | 상태 및 정보 화면 또는 호스트에서 확인 |
관련 문서
- 관리 콘솔 — 접속 · 로그인 · 화면 구성
pdCLI — 콘솔이 보여 주는 것의 원본- 웹 화면 로그인 계정