# ChemReg 운영·배포

버전 1.0.0 · 작성 2026-10-22

## 전달물과 키

`ChemReg-1.0.0-deploy.zip`에는 서비스 코드, 공개·제공 출처의 보존 자료, 가공 검색 인덱스, 20개 CSV, 로컬 OCR 자산, 설치·운영 문서가 들어갑니다. 실제 파일 수는 `package-manifest.json`과 `dist/release.json`을 기준으로 확인하세요. `.env`, API 키, 비밀번호, 사용자 업로드, 작성본, 운영 DB, 이전 프로젝트 경로, 가상환경은 포함하지 않습니다.

이 ZIP은 연구·운영 인수본입니다. 제조사 SDS, 제공된 PDF, 기관 자료의 원문 권리는 각 제공자에게 있으며 일괄 자유 재배포가 승인된 자료집은 아닙니다. 같은 설치의 접근 허용 범위와 원문별 조건을 확인하고 사용하세요. 일반 방문자에게 전체 원본을 공개하려면 별도 이용조건 검토가 필요합니다.

KOSHA 키는 운영자 자신의 계정으로 발급받습니다. 키 없는 상태에서도 기존 데이터와 작성 기능은 작동합니다. `.env.example`은 빈 설정 예시이며 `.env`는 비밀 설정입니다. 웹루트·소스 저장소·백업 공유 폴더에 노출하지 마세요. 인증 비밀번호와 세션 비밀값도 설치마다 새로 생성합니다.

## Windows 로컬

1. ZIP을 새 `ChemReg` 폴더에 풉니다.
2. Python 3.12 설치 후 `setup.cmd`를 실행합니다. 최초 패키지 설치에는 인터넷이 필요합니다.
3. `start.cmd` 실행 후 http://127.0.0.1:8766/ 에 접속합니다.
4. API 설정이 필요하면 `configure.cmd`에서 모드 1과 새 키를 입력하고 서버를 다시 시작합니다.

기본 로컬 모드는 이 PC의 loopback 주소에만 바인딩됩니다. 다른 PC의 `127.0.0.1`은 그 PC 자신을 가리킵니다. 외부 사용을 위해 단순히 `HOST=0.0.0.0`으로 바꾸면 시작을 거부하며 아래 공개 운영 설정이 필요합니다.

## Python 서버 / Linux

아래 명령은 압축을 푼 서비스 루트에서 실행합니다. 전용 서비스 계정과 쓰기 가능한 `data/` 폴더를 사용하세요.

```sh
python3.12 -m venv .venv
.venv/bin/python -m pip install -r requirements.lock.txt
.venv/bin/python scripts/configure.py
# 모드 2, 실제 HTTPS 주소, 새 운영 비밀번호(16자 이상) 입력
.venv/bin/python run.py
```

`PUBLIC_ORIGIN=https://chemreg.example.org`처럼 **전용 HTTPS 도메인 또는 서브도메인 루트**를 사용합니다. `/chemreg/` 하위 경로 설치는 지원하지 않습니다. `ALLOWED_HOSTS`에는 실제 호스트를 명시합니다. TLS는 Nginx 등 리버스 프록시에서 종료하고 내부 앱은 127.0.0.1:8766으로 연결합니다. 예시는 `deploy/nginx.conf.example`입니다. 도메인·인증서 경로를 변경하고 기존 사이트 설정과 합친 뒤 `nginx -t`로 확인하세요. 설치자의 기존 설정을 자동 덮어쓰지 않습니다.

`deploy/chemreg.service.example`은 재시작·부팅 자동 실행용 systemd 예시입니다. 서비스 계정과 `/srv/chemreg` 경로를 실제 설치에 맞게 변경합니다. 내부 앱 포트는 외부 방화벽에 개방하지 않습니다. 백업·설정·원본 폴더를 Nginx `root`나 `alias`로 공개하지 마세요.

## Docker 선택지

Python 설정 스크립트로 먼저 `.env`를 만든 뒤, 설치 루트에서 다음을 실행합니다.

```sh
# data가 현재 ChemReg 설치 안의 경로인지 확인한 뒤, 컨테이너 UID에 소유권 부여
sudo chown -R 10001:10001 ./data
docker compose build
docker compose up -d
docker compose logs --tail 50
```

동봉 compose는 외부 직접 노출 없이 `127.0.0.1:8766`에만 포트를 매핑하고 데이터는 `./data:/app/data`로 영속화합니다. `APP_MODE=public`을 강제합니다. `.env`에 HTTPS 주소·운영 비밀번호 해시·세션 비밀값이 없으면 시작하지 않습니다. 컨테이너는 비특권 사용자, 읽기 전용 루트, capability 제거 설정을 사용합니다. Docker/Linux 실행은 이 Windows 제작 환경에서 실측 검증하지 않았으므로 실제 호스트에서 아래 인수 검사를 수행하세요.

## 운영 인수 검사

1. HTTPS 첫 접속에서 로그인 화면이 보이는지 확인합니다.
2. 미로그인 상태의 `/api/msds/workbooks`, `/api/msds/uploads`, `/api/documents/...`가 401인지 확인합니다.
3. 로그인 후 저장 자료 검색, 테스트 PDF 업로드, MSDS 저장, 라벨 인쇄 미리보기와 원본 다운로드를 확인합니다.
4. 재시작 후 업로드·작성본이 유지되는지 확인합니다.
5. 로그아웃 후 이전 다운로드 주소가 열리지 않는지 확인합니다.
6. 실제 프린터에서 100% 배율, 용지 크기와 경고표지 글자·그림문자 잘림을 확인합니다.

운영 계정은 조직 단위 1개입니다. 개별 사용자·권한·조직 간 자료 분리 기능은 없습니다. 여러 조직에 제공하려면 별도 도메인·설정·데이터 폴더의 설치를 각각 운영하세요. 한 앱 프로세스를 권장하며 로그인 시도 제한은 프로세스 메모리에 보관됩니다. 인터넷 서비스는 프록시 접근 제한·로그 관리도 운영 환경에 맞게 설정합니다.

## 백업·갱신·삭제

서버를 중지한 뒤 **data 전체와 .env를 서로 구분해** 운영자 전용 백업에 저장합니다. 실행 중 DB 파일만 복사하면 최근 기록이 누락될 수 있습니다. 복구 시 동일 버전 앱에 데이터를 복원하고 파일 해시·원본 연결·작성본을 확인하세요.

업그레이드 ZIP을 기존 data 위에 무조건 덮어쓰지 않습니다. 새 디렉터리에서 검사하고 비공개 업로드·작성본·DB를 백업 후 이관합니다. 현재 버전은 공개 초기 자료를 없는 레코드에만 등록하며 기존 레코드를 자동 덮어쓰지 않습니다. 자료 최신화는 공단 조회 기능 또는 검토된 새 공개 발행본을 통해 진행합니다.

보관 기간과 삭제 담당자는 운영자가 정합니다. 현재 UI에는 영구 삭제 버튼이 없습니다. 삭제 요청 시 운영자가 업로드 UUID와 연결된 MSDS·라벨 참조를 검토한 후 비공개 저장소 및 운영 인덱스에서 처리해야 합니다. 연결 원본을 먼저 삭제하면 작성본의 원문 대조가 불가능해집니다.

## 문제 해결

- 접속 안 됨: `start.cmd`, 포트 8766, `work/server.stderr.log`를 확인합니다.
- 포트 사용 중: 다른 프로세스를 종료하지 말고 `.env`의 PORT와 프록시를 함께 수정합니다.
- 보존 데이터만 표시: 정상입니다. `configure`로 KOSHA 키를 설정하면 선택적 온라인 조회가 가능합니다.
- PDF가 비어 보임: 스캔 PDF는 텍스트 추출이 되지 않을 수 있습니다. 원본을 보며 수동 작성합니다.
- 라벨 출력 비활성: 내용이 크기를 넘치거나 폰트·그림문자가 미로드되었습니다. 크기를 늘려 새 초안을 만듭니다. 문구를 자동 삭제하지 않습니다.