Skip to content

Commit 86ef1f7

Browse files
VeteranBoLuoVeteranBoLuo
committed
Make English default and add favicon brand
1 parent f134790 commit 86ef1f7

14 files changed

Lines changed: 308 additions & 202 deletions

‎README.en.md‎

Lines changed: 0 additions & 118 deletions
This file was deleted.

‎README.ja.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
<div align="center">
22

3+
<img src="public/favicon.svg" width="88" height="88" alt="favicon-api ロゴ">
4+
35
# favicon-api
46

57
**URL 一つで、あらゆるサイトの favicon を取得。**
@@ -11,7 +13,7 @@
1113

1214
<a href="https://boluo66.top/favimg/"><img src="https://img.shields.io/badge/🚀_ライブデモ-615ced?style=for-the-badge&logoColor=white" alt="demo"></a>
1315

14-
[简体中文](README.md) | [English](README.en.md) | 日本語 | [한국어](README.ko.md)
16+
[English](README.md) · [简体中文](README.zh-CN.md) · 日本語 · [한국어](README.ko.md)
1517

1618
</div>
1719

‎README.ko.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
<div align="center">
22

3+
<img src="public/favicon.svg" width="88" height="88" alt="favicon-api 로고">
4+
35
# favicon-api
46

57
**URL 하나로 모든 사이트의 favicon 가져오기.**
@@ -11,7 +13,7 @@
1113

1214
<a href="https://boluo66.top/favimg/"><img src="https://img.shields.io/badge/🚀_라이브_데모-615ced?style=for-the-badge&logoColor=white" alt="demo"></a>
1315

14-
[简体中文](README.md) | [English](README.en.md) | [日本語](README.ja.md) | 한국어
16+
[English](README.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · 한국어
1517

1618
</div>
1719

‎README.md‎

Lines changed: 40 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,57 +1,59 @@
11
<div align="center">
22

3+
<img src="public/favicon.svg" width="88" height="88" alt="favicon-api logo">
4+
35
# favicon-api
46

5-
**一个 URL，获取任意网站的 favicon。**
7+
**Any site's favicon. One simple URL.**
68

79
[![CI](https://github.com/VeteranBoLuo/favicon-api/actions/workflows/ci.yml/badge.svg)](https://github.com/VeteranBoLuo/favicon-api/actions/workflows/ci.yml)
810
![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A518-339933?logo=nodedotjs&logoColor=white)
9-
![依赖](https://img.shields.io/badge/dependencies-0-brightgreen)
10-
[![许可证](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
11+
![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
12+
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
1113

12-
[**在线体验 →**](https://boluo66.top/favimg/) · [查看 API 示例](https://boluo66.top/favimg/?url=github.com)
14+
[**Try the live demo →**](https://boluo66.top/favimg/) · [View an API response](https://boluo66.top/favimg/?url=github.com)
1315

14-
简体中文 · [English](README.en.md) · [日本語](README.ja.md) · [한국어](README.ko.md)
16+
English · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · [한국어](README.ko.md)
1517

1618
</div>
1719

1820
---
1921

20-
一个小巧、可自托管的 Node.js API：自动发现网站真实图标，过滤假图和占位图，直连失败时使用公共图标源兜底。
22+
A small, self-hosted Node.js API that discovers real website icons, rejects fake placeholders, and falls back to public icon sources when direct requests fail.
2123

2224
```html
2325
<img src="https://boluo66.top/favimg/?url=github.com" alt="GitHub">
2426
```
2527

2628
<div align="center">
27-
<img src="https://boluo66.top/favimg/?url=baidu.com" width="56" height="56" alt="百度 favicon">&nbsp;&nbsp;
28-
<img src="https://boluo66.top/favimg/?url=bilibili.com" width="56" height="56" alt="哔哩哔哩 favicon">&nbsp;&nbsp;
29+
<img src="https://boluo66.top/favimg/?url=baidu.com" width="56" height="56" alt="Baidu favicon">&nbsp;&nbsp;
30+
<img src="https://boluo66.top/favimg/?url=bilibili.com" width="56" height="56" alt="Bilibili favicon">&nbsp;&nbsp;
2931
<img src="https://boluo66.top/favimg/?url=github.com" width="56" height="56" alt="GitHub favicon">&nbsp;&nbsp;
3032
<img src="https://boluo66.top/favimg/?url=google.com" width="56" height="56" alt="Google favicon">
3133
</div>
3234

33-
## 为什么选择 favicon-api？
35+
## Why favicon-api?
3436

35-
- **一次请求** —— `/?url=github.com` 直接返回图片，裸域名自动使用 HTTPS。
36-
- **多级发现** —— 页面图标声明 → `/favicon.ico` → 公共兜底源。
37-
- **真实图片校验** —— 拒绝 HTML 假图、1×1 像素和已知的服务商默认占位图。
38-
- **SSRF 防护** —— 首次请求及每一跳重定向前，都会拦截内网与保留地址。
39-
- **HTTP 缓存** —— 有界内存缓存、TTL、内容哈希 ETag 与 `304` 响应。
40-
- **零依赖** —— 只使用 Node.js 内置模块，无需安装依赖或构建。
37+
- **One request** — `/?url=github.com` returns an image; bare domains automatically use HTTPS.
38+
- **Resilient discovery** — page icon metadata → `/favicon.ico` → public fallback sources.
39+
- **Real-image validation** — rejects HTML responses, 1×1 pixels, and known provider placeholders.
40+
- **SSRF protection** — blocks private and reserved addresses before the initial request and every redirect hop.
41+
- **HTTP caching** — in-memory TTL cache, bounded eviction, content-based ETags, and `304` responses.
42+
- **Zero dependencies** — runs on Node.js built-ins with no install or build step.
4143

42-
## 中国大陆服务器实测
44+
## Tested from mainland China
4345

44-
2026-07-15 从中国大陆服务器测试：12 个主流中国网站与 36 个海外网站均成功返回有效图片；首批 28 个结果的内容哈希全部不同，没有返回同一张默认占位图。中国网站多数可以直连，海外网站更常依赖兜底源；Google、YouTube、X、Facebook 等首次请求可能需要约 10 秒，缓存命中后通常只需几十毫秒。
46+
On 2026-07-15, all 12 major Chinese sites and 36 international sites in our sample returned valid images from a mainland China server. The first 28 results all had unique content hashes, so they were not a shared default placeholder. Chinese sites usually work directly; international sites rely more heavily on fallback providers. A cold request for sites such as Google, YouTube, X, or Facebook can take about 10 seconds, while cached responses usually return in tens of milliseconds.
4547

46-
## 快速开始
48+
## Quick start
4749

4850
```bash
4951
git clone https://github.com/VeteranBoLuo/favicon-api.git
5052
cd favicon-api
5153
npm start
5254
```
5355

54-
打开 <http://localhost:3456> 使用交互式体验页，或直接请求图标：
56+
Open <http://localhost:3456> for the interactive playground, or request an icon directly:
5557

5658
```bash
5759
curl "http://localhost:3456/?url=github.com" -o github.svg
@@ -66,52 +68,52 @@ docker run --rm -p 3456:3456 favicon-api
6668

6769
## API
6870

69-
### `GET /?url=<域名或URL>`
71+
### `GET /?url=<domain-or-url>`
7072

7173
```text
7274
https://boluo66.top/favimg/?url=github.com
7375
https://boluo66.top/favimg/?url=https%3A%2F%2Fgithub.com%2Fopenai
7476
```
7577

76-
成功响应返回图片二进制，并包含：
78+
Successful responses contain the image binary and these useful headers:
7779

78-
| 响应头 | 说明 |
80+
| Header | Description |
7981
| --- | --- |
80-
| `Content-Type` | 检测到的图片类型 |
81-
| `Cache-Control` | 浏览器与 CDN 缓存策略 |
82-
| `ETag` | 基于内容生成，支持 `If-None-Match` |
83-
| `X-Favicon-Source` | 重定向或兜底后的最终来源 URL |
82+
| `Content-Type` | Detected image type |
83+
| `Cache-Control` | Browser and CDN cache policy |
84+
| `ETag` | Content-based validator; supports `If-None-Match` |
85+
| `X-Favicon-Source` | Final source URL after redirects or fallback |
8486

85-
失败时返回 JSON：`{ "error": "..." }`，状态码为 `400`、`403`、`404` 或 `502`。
87+
Errors use JSON: `{ "error": "..." }` with `400`, `403`, `404`, or `502` status codes.
8688

8789
### `GET /health`
8890

8991
```json
9092
{ "status": "ok" }
9193
```
9294

93-
## 工作原理
95+
## How it works
9496

95-
1. 标准化输入 URL，并拒绝内网和保留地址。
96-
2. 短超时抓取网页，手动处理并逐跳检查重定向目的地。
97-
3. 选择网页声明的最佳图标；没有声明时尝试 `/favicon.ico`。
98-
4. 按文件特征验证图片，过滤过小图片与已知占位图。
99-
5. 直连失败时尝试公共兜底源，然后缓存有效结果。
97+
1. Normalize the input URL and reject private or reserved destinations.
98+
2. Fetch the page with a short timeout and manually validate every redirect destination.
99+
3. Select the best icon declared by the page, otherwise try `/favicon.ico`.
100+
4. Validate the image signature and reject tiny or known placeholder images.
101+
5. Try public fallback sources when direct discovery fails, then cache the valid result.
100102

101-
## 安全与隐私
103+
## Security and privacy
102104

103-
服务会访问用户提交的公开 URL。它会拦截内网、回环、链路本地、文档示例等保留地址，限制重定向次数与响应大小，并重新检查每一个重定向目的地。若生产环境安全等级较高，仍建议配置网络出口规则，以进一步降低 DNS rebinding 风险。
105+
This service fetches user-supplied public URLs. It blocks private, loopback, link-local, documentation, and other reserved address ranges; limits redirect hops and response sizes; and re-checks each redirect destination. DNS rebinding cannot be eliminated completely without pinning DNS resolution to the outbound connection, so use additional egress controls for high-trust production environments.
104106

105-
兜底请求可能把目标域名发送给 `favicone.com` 或 Yandex。如果你的环境不能使用第三方服务，可以在 [`src/favicon.js`](src/favicon.js) 中删除或替换 `AGGREGATOR_BUILDERS`。
107+
Fallback requests may send the requested hostname to `favicone.com` or Yandex. Remove or replace `AGGREGATOR_BUILDERS` in [`src/favicon.js`](src/favicon.js) if your environment must avoid third-party services.
106108

107-
## 开发
109+
## Development
108110

109111
```bash
110112
npm test
111113
npm run check
112114
```
113115

114-
欢迎贡献代码和可复现的边界案例，参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
116+
Contributions and reproducible edge cases are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
115117

116118
## License
117119

0 commit comments

Comments
 (0)