# 설정

설정값의 기본값은 [config.js](../config.js)에 있습니다. 이 파일은 직접 고치지 말고 아래 방법을 쓰세요.
**우선순위:** 환경변수 > `config.<NODE_ENV>.js` > `config.js`

## 환경변수 (도커에서는 이 방법)

모든 설정은 `PSITRANSFER_` 접두사와 대문자 스네이크 표기로 바꿀 수 있습니다.
(`defaultRetention` → `PSITRANSFER_DEFAULT_RETENTION`)

```bash
export PSITRANSFER_PORT=8080
export PSITRANSFER_RETENTIONS='{"one-time":"1회 다운로드","86400":"1일"}'
export PSITRANSFER_QUICK_RETENTIONS=one-time,86400
node app.js
```

값의 형식은 기본값의 형식을 따릅니다. 숫자는 정수로, 목록(`quickRetentions`)은 쉼표로 구분하고,
`retentions`는 JSON으로 적고, `requireBucketPassword`와 `disableQrCode`는 `true`/`false`로 적습니다.

## 설정 파일

`config.<NODE_ENV>.js`가 있으면 `config.js` 위에 덮어씁니다. `NODE_ENV=dev node app.js`는 [config.dev.js](../config.dev.js)를
사용합니다. 직접 만든 이름(`config.custom.js`)도 `NODE_ENV=custom node app.js`로 쓸 수 있습니다.

## 설정 목록

### 서버와 경로

| 설정 | 기본값 | 설명 |
|---|---|---|
| `uploadDir` | `./data` | 파일과 관리자 설정을 저장하는 폴더. 도커에서는 `/data` |
| `settingsDir` | `<uploadDir>/.settings` | 관리자 설정(이름, 로고)을 저장하는 폴더 |
| `baseUrl` | `/` | 하위 경로로 서비스할 때 (`/sharing`) |
| `uploadAppPath` | `/` | 업로드 화면의 주소 (`baseUrl` 아래) |
| `iface`, `port` | `0.0.0.0`, `3000` | 수신 주소와 HTTP 포트 (`port`를 `false`로 두면 HTTP 끔) |
| `sslPort`, `sslKeyFile`, `sslCertFile` | | 직접 HTTPS를 쓸 때. 세 값을 모두 지정해야 켜집니다 |
| `forceHttps` | | HTTPS로 강제 이동. `true` 또는 이동할 주소 |
| `trustProxy` | | 리버스 프록시 뒤에서 실제 IP를 로그에 남길 때 ([Express 문서](https://expressjs.com/en/guide/behind-proxies.html)) |
| `accessLog` | `:date[iso] ...` | [morgan](https://github.com/expressjs/morgan) 형식. `false`면 로그 끔 |

### 업로드와 보관

| 설정 | 기본값 | 설명 |
|---|---|---|
| `retentions` | 1회, 1시간 ~ 8주 | 선택할 수 있는 보관 기간. `초: 이름` (`one-time`은 1회 다운로드). 화면에 보이는 이름은 언어 파일의 `retentions`가 우선합니다 |
| `quickRetentions` | `one-time,86400,259200,432000,604800` | 버튼으로 보이는 보관 기간. 나머지는 "그 외" 목록에 들어갑니다 |
| `defaultRetention` | `604800` | 처음 선택돼 있는 보관 기간 |
| `requireBucketPassword` | `true` | 업로드에 비밀번호를 필수로 합니다. **1회 다운로드는 예외**입니다. 서버에서도 검사합니다 |
| `maxAge` | 75일 | 어떤 파일도 이 시간(초)이 지나면 삭제됩니다. 다운로드되지 않은 1회 다운로드 파일에도 적용됩니다 |
| `maxFileSize`, `maxBucketSize` | 제한 없음 | 파일 하나, 한 번에 올리는 전체의 최대 크기(바이트) |
| `maxPreviewSize` | 2MB | 텍스트 미리보기에서 읽는 최대 크기 |
| `mailTemplate` | `mailto:?subject=...` | 이메일 버튼의 `mailto:` 주소. `%%URL%%`이 다운로드 링크로 바뀝니다 |
| `disableQrCode` | `false` | QR 코드 버튼 숨기기 |
| `defaultLanguage` | `ko` | 브라우저 언어를 알 수 없을 때 쓰는 언어 |

### 로그인과 관리자

| 설정 | 기본값 | 설명 |
|---|---|---|
| `uploadPass` | 없음 | 업로드 비밀번호. 없으면 누구나 올릴 수 있습니다 |
| `adminPass` | 없음 | 관리자 비밀번호. 없으면 `/admin` 페이지가 없습니다 |
| `tokenTtl` | 7일 | 로그인 유지 시간(초). 사용할 때마다 새로 7일이 됩니다 |
| `tokenSecret` | | 로그인 토큰의 서명 키. 비워 두면 두 비밀번호에서 만들어집니다 |

### 이름과 로고 (기본값)

| 설정 | 기본값 | 설명 |
|---|---|---|
| `appName` | `Dodo Transfer` | 서비스 이름 |
| `appOwner` | `아진산업(주) 전장선행개발팀` | 하단 저작권 표기의 소유자 |
| `appFromYear` | `2026` | 하단 저작권 표기의 시작 연도 (현재 연도가 더 크면 `2026–2027`처럼 표시) |

이 값들은 **기본값**입니다. 관리자 페이지의 설정 탭에서 바꾼 값이 있으면 그것이 우선합니다.

## 로그인 방식

업로드 비밀번호를 설정하면 처음 접속할 때 로그인 화면이 나옵니다.

* 로그인하면 서버가 서명된 토큰을 발급하고, 브라우저가 이를 보관합니다. 비밀번호 자체는 저장하지 않습니다.
* 토큰은 페이지에 접속할 때마다 갱신되어 7일(`tokenTtl`) 동안 유지됩니다.
* 서버에는 로그인 상태가 저장되지 않습니다. 그래서 컨테이너를 다시 시작하거나 다시 만들어도 로그인이 유지됩니다.
* `uploadPass`나 `adminPass`를 바꾸면 이전에 발급된 토큰이 모두 무효가 됩니다. 비밀번호를 바꿔도 로그인을
  유지하려면 `tokenSecret`을 지정하세요.
* 스크립트(curl)를 위해 `x-passwd: <업로드 비밀번호>` 헤더도 계속 받습니다.

## 비밀번호 규칙

* 보관 기간이 1회 다운로드가 아니면 비밀번호가 필수입니다 (`requireBucketPassword`).
* 업로드할 때 **"인증된 사용자는 비밀번호 없이 다운로드"** 를 켜 두면(기본), 업로드 로그인 상태인 브라우저는
  다운로드 링크를 열 때 비밀번호를 묻지 않습니다. 로그인하지 않은 사람(외부 수신자)은 비밀번호를 입력해야 합니다.
  업로드 비밀번호가 없는 환경에서는 이 선택지가 나타나지 않습니다.

## 관리자 페이지

`adminPass`를 설정하면 `<BASE_URL>/admin`에서 다음을 할 수 있습니다.

* **파일 관리:** 올라온 파일 조회, 검색, 정렬, 미리보기, 다운로드(파일, zip, tar.gz), 삭제(파일, bucket 단위).
  관리자 다운로드는 1회 다운로드 파일을 소모하지 않고 다운로드 횟수에도 집계되지 않습니다.
  파일을 삭제하면 받는 사람 화면에서도 바로 사라집니다.
* **설정:** 서비스 이름, 로고(PNG, SVG, WebP, 1MB 이하), 하단 저작권 표기. 저장하면 모든 화면에 바로 적용됩니다.

설정은 `settingsDir`(기본 `/data/.settings`)에 저장됩니다. 로고를 처음 상태로 되돌리려면 설정 탭의
"기본 로고로 되돌리기"를 누르세요. 아진산업 로고 파일은 [docs/brand/ajin-logo.png](brand/ajin-logo.png)에 있습니다.

## SSL

nginx에서 SSL을 처리하는 것을 권장합니다. [nginx-ssl-example.conf](nginx-ssl-example.conf)를 참고하세요.
직접 처리하려면 `sslPort`, `sslKeyFile`, `sslCertFile`을 모두 지정합니다. 테스트용 인증서는
`openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout cert.key -out cert.pem`으로 만듭니다.

## 웹훅

다른 시스템과 연동하려면 이벤트가 생길 때 POST 요청을 받을 주소를 지정합니다.

### fileUploadedWebhook

파일 하나의 업로드가 끝날 때마다 호출됩니다. 비밀번호는 보내지 않고 `_password: true`로 표시합니다.

```json
{
  "metadata": {
    "sid": "6055ab792b6c",
    "retention": "3600",
    "_password": true,
    "name": "test.png",
    "comment": "파일 코멘트",
    "type": "image/png",
    "key": "135a3814-df46-4e23-b061-03bdda13425c",
    "createdAt": "1589276618052"
  },
  "date": 1589276619385
}
```

여러 파일을 한 번에 올리면 파일마다 호출됩니다 (`sid`는 같고 `key`가 다릅니다).
파일 주소는 `https://<호스트>/<BASE_URL>files/<sid>++<key>`입니다.

### fileDownloadedWebhook

받는 사람이 파일(또는 전체 받기)을 다운로드할 때 호출됩니다. 미리보기와 관리자 다운로드는 호출하지 않습니다.

```json
{
  "fid": "6055ab792b6c",
  "file": "test.png",
  "date": 1589276619415
}
```