요약: Total 986, Timeouts 3, Errors 0. step 67초. 다음 run 367은 Timeouts 0, 노트북 curl 9회 모두 200 → 링크는 살아 있다(재현 안 됨 9/9, 분류: 외부).
main이 빨강이면 같은 repo의 병합이 멈춘다(design-docs ci/manual.md 9.3절). v0.24.2로 올린 뒤 main.yml run에서 links 실패는 이것 하나다.
이 PR은 lychee 재시도 창을 넓힌다: --max-retries 5 --retry-wait-time 5. 시간 초과·429를 받은 요청을 5·10·20·40·80초 뒤에 다시 묻는다. 시간 초과가 이어지면 마지막 시도는 첫 시도 4분쯤 뒤에 시작한다(바로 오는 429는 2분 반쯤). 그 안에 답하면 통과, 마지막 시도에도 답이 없으면 지금처럼 실패다.
고른 방법과 버린 대안
고름: (가) 재시도 창 넓히기. 시간 초과는 그대로 실패로 둔다.
버림:
--accept-timeouts(시간 초과만이면 exit 0): 처음 고른 안이었다. 리뷰에서 「패킷을 버리는 죽은 호스트와 바깥으로 나가지 못하는 runner를 초록으로 둔다」(거짓 통과)는 지적을 받아 버렸다.
(나) 기록 문서(docs/design·history·reviews)의 외부 링크를 main 실패에서 빼기: 외부 URL 고유 364개 중 345개가 기록이라 효과는 크다. 하지만 기록의 404까지 안 보게 되고, docs/README.md 「기록의 죽은 링크는 .lycheeignore에 더한다」 규칙을 바꾼다. 살아 있는 문서의 시간 초과는 그대로 빨강이다.
--timeout도 늘리기: 한 번에 하나만 바꾼다(ci/manual.md 11절 4). run 362 로그로는 느린 응답인지 응답 없음인지 가릴 수 없다.
인자가 v0.24.2에 있다는 근거(lychee-v0.24.2 태그 소스·README):
lychee-bin/src/config/mod.rs: max_retries 「Maximum number of retries per request [default: 3]」 #[arg(long)], retry_wait_time 「Minimum wait time in seconds between retries of failed requests [default: 1]」 #[arg(short, long)], timeout 기본 20.
lychee-lib/src/checker/website.rsretry_request: 첫 시도 뒤 max_retries번, 매번 tokio::time::sleep(wait_time) 후 wait_time.saturating_mul(2).
lychee-lib/src/retry.rs: 다시 묻는 것은 Status::Timeout, reqwest timeout, 429. 응답으로 받은 500·503과 connect 오류는 다시 묻지 않는다.
README 「Commandline Parameters」에도 같은 세 옵션이 있다. run 362 로그 114·169줄 lycheeVersion: v0.24.2.
위험과 영향
4분 넘게 답하지 않는 사이트는 여전히 main을 빨갛게 한다. 그런 링크 하나는 4분 반쯤 걸린다(시도 6번 × 20초 + 대기 155초).
호스트 하나가 통째로 답하지 않아도 lychee는 시도마다 호스트별 자리(기본 10)를 받고 대기 중에는 쥐지 않는다. 범위에서 URL이 가장 많은 docs.aws.amazon.com 53개가 53 × 6 × 20초 ÷ 10 ≈ 11분이다. timeout-minutes: 15 안이다.
이 기계들(노트북·desktop)에는 lychee가 없고 내려받아 설치하지 않는다(docs/work/operate.md 4.1절). 재시도 동작은 위 소스로만 확인했다. 효과는 병합 뒤 main run의 links job으로 본다.
운영 코드·HTTP 응답은 바뀌지 않는다. 파생 서비스는 main.yml을 받으면 같은 인자를 얻는다(따라 고칠 것 없음).
## 무엇을, 왜
main `links` job(lychee-action v2.9.0 = lychee v0.24.2)이 run 362(f415bdbb)에서 빨강이었다. 기록 문서 둘의 외부 링크 셋이 lychee 기본 재시도 동안 답하지 않았다.
- `https://man7.org/linux/man-pages/man2/openat2.2.html` (docs/design fileserver 설계)
- `https://jdbc.postgresql.org/documentation/ssl/`, `.../use/` (docs/design jpa 설계)
- 요약: Total 986, Timeouts 3, Errors 0. step 67초. 다음 run 367은 Timeouts 0, 노트북 curl 9회 모두 200 → 링크는 살아 있다(재현 안 됨 9/9, 분류: 외부).
- main이 빨강이면 같은 repo의 병합이 멈춘다(design-docs `ci/manual.md` 9.3절). v0.24.2로 올린 뒤 main.yml run에서 links 실패는 이것 하나다.
이 PR은 lychee 재시도 창을 넓힌다: `--max-retries 5 --retry-wait-time 5`. 시간 초과·429를 받은 요청을 5·10·20·40·80초 뒤에 다시 묻는다. 시간 초과가 이어지면 마지막 시도는 첫 시도 4분쯤 뒤에 시작한다(바로 오는 429는 2분 반쯤). 그 안에 답하면 통과, 마지막 시도에도 답이 없으면 지금처럼 실패다.
## 고른 방법과 버린 대안
고름: (가) 재시도 창 넓히기. 시간 초과는 그대로 실패로 둔다.
버림:
- `--accept-timeouts`(시간 초과만이면 exit 0): 처음 고른 안이었다. 리뷰에서 「패킷을 버리는 죽은 호스트와 바깥으로 나가지 못하는 runner를 초록으로 둔다」(거짓 통과)는 지적을 받아 버렸다.
- (나) 기록 문서(docs/design·history·reviews)의 외부 링크를 main 실패에서 빼기: 외부 URL 고유 364개 중 345개가 기록이라 효과는 크다. 하지만 기록의 404까지 안 보게 되고, `docs/README.md` 「기록의 죽은 링크는 `.lycheeignore`에 더한다」 규칙을 바꾼다. 살아 있는 문서의 시간 초과는 그대로 빨강이다.
- `--timeout`도 늘리기: 한 번에 하나만 바꾼다(`ci/manual.md` 11절 4). run 362 로그로는 느린 응답인지 응답 없음인지 가릴 수 없다.
인자가 v0.24.2에 있다는 근거(lychee-v0.24.2 태그 소스·README):
- `lychee-bin/src/config/mod.rs`: `max_retries` 「Maximum number of retries per request [default: 3]」 `#[arg(long)]`, `retry_wait_time` 「Minimum wait time in seconds between retries of failed requests [default: 1]」 `#[arg(short, long)]`, `timeout` 기본 20.
- `lychee-lib/src/checker/website.rs` `retry_request`: 첫 시도 뒤 `max_retries`번, 매번 `tokio::time::sleep(wait_time)` 후 `wait_time.saturating_mul(2)`.
- `lychee-lib/src/retry.rs`: 다시 묻는 것은 `Status::Timeout`, reqwest timeout, 429. 응답으로 받은 500·503과 connect 오류는 다시 묻지 않는다.
- README 「Commandline Parameters」에도 같은 세 옵션이 있다. run 362 로그 114·169줄 `lycheeVersion: v0.24.2`.
## 위험과 영향
- 4분 넘게 답하지 않는 사이트는 여전히 main을 빨갛게 한다. 그런 링크 하나는 4분 반쯤 걸린다(시도 6번 × 20초 + 대기 155초).
- 호스트 하나가 통째로 답하지 않아도 lychee는 시도마다 호스트별 자리(기본 10)를 받고 대기 중에는 쥐지 않는다. 범위에서 URL이 가장 많은 docs.aws.amazon.com 53개가 53 × 6 × 20초 ÷ 10 ≈ 11분이다. `timeout-minutes: 15` 안이다.
- 이 기계들(노트북·desktop)에는 lychee가 없고 내려받아 설치하지 않는다(`docs/work/operate.md` 4.1절). 재시도 동작은 위 소스로만 확인했다. 효과는 병합 뒤 main run의 `links` job으로 본다.
- 운영 코드·HTTP 응답은 바뀌지 않는다. 파생 서비스는 main.yml을 받으면 같은 인자를 얻는다(따라 고칠 것 없음).
## 검증
| 단계 | 명령 | 트리 | 결과 | 로그(desktop) |
| --- | --- | --- | --- | --- |
| RED | `:app-bootstrap:repositoryContractTest --tests DeveloperExperienceContractTest --no-build-cache` (기준 59349a2b + 시험만) | 5eb884c1 | rc=1, 16개 중 1 실패(`--max-retries` 없음) | `~/be-ci-next-logs/a1-red3.log` |
| GREEN | 같은 시험 + `:app-bootstrap:spotlessCheck`, 그다음 `:verifyStrictLaneStages --dry-run` | 1f3b1877 | rc=0, 16개 통과, spotlessCheck·dry-run rc=0, FROM-CACHE 0 | `~/be-ci-next-logs/a1-green4.log` |
| 문서 | `scripts/verify.sh docs`(노트북) | 같은 트리 | rc=0 | — |
- 리뷰 1회(렌즈 be-build-ci·be-docs): Medium 1(`--accept-timeouts` 거짓 통과), Low 1(실패 목록에 5xx 누락) → 고침. 확인 리뷰 1회: Low 1(429와 기본값의 시간 숫자) → 고침.
- 흔들림 장부 `docs/ledger/flaky-tests.jsonl`에 run 362를 `external`로 한 줄 더했다. `fixed_by`는 병합 뒤 다음 PR에서 채운다.
- 병합 뒤 볼 것: main push run의 `links` success.
## 리뷰어가 볼 곳
- `.gitea/workflows/main.yml` links job 주석과 `args` 두 줄
- `DeveloperExperienceContractTest#linkCheckScansTheExactDocumentationScopeAndFails`의 인자 목록
- `docs/work/reference/gates.md` 「링크 검사」 문단
## 관련
- brief be-ci-next (1), design-docs `ci/manual.md` 8·9·11절
- 커밋 둘: 장부 착수 예측 한 줄, links 재시도
백엔드 CI 후속 셋(links 외부 시간 초과, API surface 빈 root, BE-1·BE-4)을
시작하며 docs/work/README.md 6절대로 예측 한 줄을 더한다. 실측 줄은 일이
끝날 때 더한다.
검증: ledger.py append가 칸을 검사했다. scripts/verify.sh docs rc=0(노트북).
문제: main links job(lychee-action v2.9.0 = lychee v0.24.2)이 run 362
(f415bdbb)에서 빨강이었다. 기록 문서 둘의 외부 링크 셋(man7.org의
openat2.2, jdbc.postgresql.org의 documentation/ssl·use)이 lychee 기본
재시도(첫 시도 뒤 3회, 대기 1·2·4초, 시한 20초) 동안 답하지 않았다. 요약은
Timeouts 3, Errors 0이었고 step은 67초 걸렸다. 링크는 살아 있었다. 다음 run
367은 Timeouts 0이고, 노트북 curl 9회가 모두 200이었다. main이 빨강이면 같은
repo의 병합이 멈춘다(design-docs ci/manual.md 9.3절).
고른 방법: --max-retries 5 --retry-wait-time 5. 시간 초과나 429를 받은
요청을 5·10·20·40·80초 뒤에 다시 묻는다. 시도마다 20초 시한이라 시간 초과가
이어지면 마지막 시도는 첫 시도 4분쯤 뒤에 시작한다(바로 오는 429는 2분
반쯤). 그 안에 다시 답하면 통과하고, 마지막 시도에도 답이 없으면 지금처럼
실패한다. 근거는
lychee-v0.24.2 태그 소스다: lychee-bin/src/config/mod.rs의 max_retries
("Maximum number of retries per request", 기본 3)와 retry_wait_time
("Minimum wait time in seconds between retries of failed requests", 기본 1),
lychee-lib/src/checker/website.rs의 retry_request(첫 시도 뒤 max_retries번,
대기는 매번 두 배), lychee-lib/src/retry.rs(시간 초과와 429만 다시 묻는다).
버린 대안:
- --accept-timeouts(시간 초과만이면 exit 0): 처음 고른 안이었다. 리뷰에서
패킷을 버리는 죽은 호스트와 바깥으로 나가지 못하는 runner를 초록으로 둔다는
지적을 받아 버렸다. 게이트가 막겠다던 것을 조용히 못 막는다.
- 기록 문서(docs/design·history·reviews)의 외부 링크를 main 실패에서 빼기:
외부 URL 고유 364개 중 345개가 기록이라 효과는 크다. 하지만 기록의 404까지
안 보게 되고, 「기록의 죽은 링크는 .lycheeignore에 더한다」는
docs/README.md 규칙을 바꾼다. 살아 있는 문서의 시간 초과는 그대로 빨강이다.
- 시한(--timeout)도 늘리기: 한 번에 하나만 바꾼다(ci/manual.md 11절 4).
run 362 로그로는 느린 응답인지 응답 없음인지 가릴 수 없다.
위험·한계: 4분 넘게 답하지 않는 사이트는 여전히 main을 빨갛게 한다. 그런
링크 하나는 4분 반쯤 걸린다(시도 6번 × 20초 + 대기 155초). 호스트 하나가
통째로 답하지 않아도 lychee는 시도마다 호스트별 자리(기본 10)를 받고 대기
중에는 쥐지 않으므로, 범위에서 URL이 가장 많은 docs.aws.amazon.com 53개가
53 × 6 × 20초 ÷ 10 ≈ 11분이다. timeout-minutes 15 안이다. 이 기계들에는
lychee가 없고 내려받아 설치하지 않으므로, 재시도 동작은 위 소스로만
확인했다. 효과는 병합 뒤 main run의 links job으로 본다. 흔들림 장부에 run
362를 external로 한 줄 더했다.
검증:
- 계약 시험 RED: 기준 59349a2b에 시험만 얹은 트리 5eb884c1에서
DeveloperExperienceContractTest 16개 중 1개 실패(--max-retries 없음).
desktop ~/be-ci-next-logs/a1-red3.log.
- GREEN: 트리 1f3b1877에서 같은 클래스 16개 통과,
:app-bootstrap:spotlessCheck, :verifyStrictLaneStages --dry-run rc=0,
--no-build-cache, FROM-CACHE 0. ~/be-ci-next-logs/a1-green4.log.
- scripts/verify.sh docs rc=0(노트북).
- 리뷰 1회(be-build-ci·be-docs): Medium 1(위 --accept-timeouts), Low 1(실패
목록에서 5xx 누락) → 둘 다 고침. 확인 리뷰: Low 1(429와 기본값의 시간
숫자) → 고침.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
무엇을, 왜
main
linksjob(lychee-action v2.9.0 = lychee v0.24.2)이 run 362(f415bdbb)에서 빨강이었다. 기록 문서 둘의 외부 링크 셋이 lychee 기본 재시도 동안 답하지 않았다.https://man7.org/linux/man-pages/man2/openat2.2.html(docs/design fileserver 설계)https://jdbc.postgresql.org/documentation/ssl/,.../use/(docs/design jpa 설계)ci/manual.md9.3절). v0.24.2로 올린 뒤 main.yml run에서 links 실패는 이것 하나다.이 PR은 lychee 재시도 창을 넓힌다:
--max-retries 5 --retry-wait-time 5. 시간 초과·429를 받은 요청을 5·10·20·40·80초 뒤에 다시 묻는다. 시간 초과가 이어지면 마지막 시도는 첫 시도 4분쯤 뒤에 시작한다(바로 오는 429는 2분 반쯤). 그 안에 답하면 통과, 마지막 시도에도 답이 없으면 지금처럼 실패다.고른 방법과 버린 대안
고름: (가) 재시도 창 넓히기. 시간 초과는 그대로 실패로 둔다.
버림:
--accept-timeouts(시간 초과만이면 exit 0): 처음 고른 안이었다. 리뷰에서 「패킷을 버리는 죽은 호스트와 바깥으로 나가지 못하는 runner를 초록으로 둔다」(거짓 통과)는 지적을 받아 버렸다.docs/README.md「기록의 죽은 링크는.lycheeignore에 더한다」 규칙을 바꾼다. 살아 있는 문서의 시간 초과는 그대로 빨강이다.--timeout도 늘리기: 한 번에 하나만 바꾼다(ci/manual.md11절 4). run 362 로그로는 느린 응답인지 응답 없음인지 가릴 수 없다.인자가 v0.24.2에 있다는 근거(lychee-v0.24.2 태그 소스·README):
lychee-bin/src/config/mod.rs:max_retries「Maximum number of retries per request [default: 3]」#[arg(long)],retry_wait_time「Minimum wait time in seconds between retries of failed requests [default: 1]」#[arg(short, long)],timeout기본 20.lychee-lib/src/checker/website.rsretry_request: 첫 시도 뒤max_retries번, 매번tokio::time::sleep(wait_time)후wait_time.saturating_mul(2).lychee-lib/src/retry.rs: 다시 묻는 것은Status::Timeout, reqwest timeout, 429. 응답으로 받은 500·503과 connect 오류는 다시 묻지 않는다.lycheeVersion: v0.24.2.위험과 영향
timeout-minutes: 15안이다.docs/work/operate.md4.1절). 재시도 동작은 위 소스로만 확인했다. 효과는 병합 뒤 main run의linksjob으로 본다.검증
:app-bootstrap:repositoryContractTest --tests DeveloperExperienceContractTest --no-build-cache(기준59349a2b+ 시험만)--max-retries없음)~/be-ci-next-logs/a1-red3.log:app-bootstrap:spotlessCheck, 그다음:verifyStrictLaneStages --dry-run1f3b1877~/be-ci-next-logs/a1-green4.logscripts/verify.sh docs(노트북)--accept-timeouts거짓 통과), Low 1(실패 목록에 5xx 누락) → 고침. 확인 리뷰 1회: Low 1(429와 기본값의 시간 숫자) → 고침.docs/ledger/flaky-tests.jsonl에 run 362를external로 한 줄 더했다.fixed_by는 병합 뒤 다음 PR에서 채운다.linkssuccess.리뷰어가 볼 곳
.gitea/workflows/main.ymllinks job 주석과args두 줄DeveloperExperienceContractTest#linkCheckScansTheExactDocumentationScopeAndFails의 인자 목록docs/work/reference/gates.md「링크 검사」 문단관련
ci/manual.md8·9·11절