网络端口与防火墙

OCTO 文档中心 · 部署运维

docker/docker-compose.yaml
docker/nginx/conf.d/octo.conf.template
docker/nginx/nginx.conf
docker/.env.example
helm/octo/values.yaml

网络端口与防火墙清单 v1.0

本文档列出 OCTO Docker Compose 部署的所有网络端口、Nginx 路由、防火墙建议和安全注意事项。读完本文应能直接配置生产防火墙规则。

§1 端口总览表

1.1 外部必开端口（默认部署）

服务名	Host 端口	容器端口	协议	默认绑定	防火墙开放	用途	来源
nginx	28080	80	TCP	`0.0.0.0`	是（唯一默认对外端口）	统一 HTTP 入口，所有外部流量经此	docker-compose.yaml: `ports`; .env.example: `OCTO_HTTP_PORT=28080`, `OCTO_NGINX_BIND=0.0.0.0`

单端口设计：默认部署只需开放 TCP 28080。所有服务（Web/Admin/API/WS/MinIO文件）均经 Nginx 反向代理访问。MinIO S3 预签名 URL 通过 `/{bucket}/{key}` 路径经 Nginx 转发，保留 SigV4 签名路径不变。

1.2 内部服务端口（默认绑定 127.0.0.1，不应开放防火墙）

服务名	Host 端口	容器端口	协议	默认绑定	防火墙开放	用途	来源
mysql	23306	3306	TCP	`127.0.0.1`	否	MySQL 数据库	.env.example: `OCTO_MYSQL_PORT=23306`, `OCTO_MYSQL_BIND=127.0.0.1`
redis	26379	6379	TCP	`127.0.0.1`	否（无密码！）	Redis 缓存/会话	.env.example: `OCTO_REDIS_PORT=26379`, `OCTO_REDIS_BIND=127.0.0.1`
minio API	29000	9000	TCP	`127.0.0.1`	否（经 Nginx 代理）	MinIO S3 API	.env.example: `OCTO_MINIO_API_PORT=29000`, `OCTO_MINIO_API_BIND=127.0.0.1`
minio Console	29001	9001	TCP	`127.0.0.1`	否（SSH 隧道访问）	MinIO 管理控制台	.env.example: `OCTO_MINIO_CONSOLE_PORT=29001`, `OCTO_MINIO_CONSOLE_BIND=127.0.0.1`
wukongim Manager API	25001	5001	TCP	`127.0.0.1`	否（内部管理API）	WuKongIM 管理/调试 API	.env.example: `OCTO_WK_API_PORT=25001`, `OCTO_WK_API_BIND=127.0.0.1`
wukongim TCP	25100	5100	TCP	`127.0.0.1`	否（WS 经 Nginx）	WuKongIM 原生 TCP 长连接	.env.example: `OCTO_WK_TCP_PORT=25100`, `OCTO_WK_TCP_BIND=127.0.0.1`
wukongim WS	25200	5200	TCP	`127.0.0.1`	否（经 Nginx `/ws`）	WuKongIM WebSocket	.env.example: `OCTO_WK_WS_PORT=25200`, `OCTO_WK_WS_BIND=127.0.0.1`
wukongim Monitor	25300	5300	TCP	`127.0.0.1`	否	WuKongIM 监控/varz	.env.example: `OCTO_WK_MONITOR_PORT=25300`, `OCTO_WK_MONITOR_BIND=127.0.0.1`
octo-server	28081	8090	TCP	`127.0.0.1`	否（经 Nginx `/api/`）	OCTO REST API 直连端口（绕过限流）	docker-compose.yaml: octo-server ports
web (SPA)	28083	80	TCP	`127.0.0.1`	否（经 Nginx `/`）	Web 前端直连端口	docker-compose.yaml: web ports
admin	28082	80	TCP	`127.0.0.1`	否（经 Nginx `/admin/`）	管理后台直连端口	docker-compose.yaml: admin ports
matter	28086	8080	TCP	`127.0.0.1`	否（经 Nginx `/matter/`）	任务/AI 助手服务直连	docker-compose.yaml: matter ports

1.3 Profile 可选模块端口（启用对应 Profile 后才启动）

服务名	Host 端口	容器端口	协议	默认绑定	Profile	防火墙开放	用途	来源
summary-api	28087	8080	TCP	`127.0.0.1`	`summary`	否（经 Nginx `/summary/`）	智能摘要 API	docker-compose.yaml: summary-api ports
summary-worker	无 host 映射	8082	TCP（内部）	—	`summary`	否	摘要 Worker（内部回调）	docker-compose.yaml: summary-worker（无 ports 段）
octo-speech	无 host 映射	8780	TCP（内部）	—	`speech`	否	语音转写 API（内部调用）	docker-compose.yaml: octo-speech（无 ports 段）
octo-speech-admin	28088	8781	TCP	`127.0.0.1`	`speech`	否（SSH 隧道访问）	语音 API Key 管理控制台	docker-compose.yaml: octo-speech-admin ports; .env.example: `OCTO_SPEECH_ADMIN_PORT=28088`
search-kafka	29092	29092	TCP	`127.0.0.1`	`search`	否	Kafka（EXTERNAL listener，本地验证用）	docker-compose.yaml: search-kafka ports
search-opensearch	29200	9200	TCP	`127.0.0.1`	`search`	否	OpenSearch REST API	docker-compose.yaml: search-opensearch ports
es-indexer	无 host 映射	无 host 映射	TCP（内部）	—	`search`	否	Kafka→OpenSearch 索引器（纯内部消费）	docker-compose.yaml: es-indexer（无 ports 段）
search-producer	无 host 映射	无 host 映射	TCP（内部）	—	`search-producer`	否	独立 MySQL→Kafka 生产者	docker-compose.yaml: search-producer（无 ports 段）

1.4 容器间通信端口（不映射到 Host，仅 octo-net 内部）

服务名	容器端口	协议	通信方	用途	来源
octo-server	8090	TCP	nginx → octo-server	REST API（nginx upstream `octo_api`）	octo.conf.template: `upstream octo_api`
wukongim	5200	TCP	nginx → wukongim	WebSocket（nginx upstream `octo_ws`）	octo.conf.template: `upstream octo_ws`
minio	9000	TCP	nginx → minio; octo-server → minio	S3 API（nginx upstream `octo_minio_api`）	octo.conf.template: `upstream octo_minio_api`
marketplace	8092	TCP	nginx → marketplace	市场/技能商店 API（nginx `/market/api/`）	docker-compose.yaml: marketplace `API_PORT: "8092"`
octo-speech	8780	TCP	octo-server → octo-speech	语音转写内部调用	docker-compose.yaml: octo-speech `SPEECH_SERVICE_PORT: "8780"`
octo-docs-backend	3000	TCP	nginx → octo-docs-backend	文档 REST API（nginx `/docs-api/`）	docker-compose.yaml: octo-docs-backend `HTTP_PORT: "3000"`
octo-docs-backend	1234	TCP	nginx → octo-docs-backend	文档协作 WebSocket（nginx `/docs-ws/`）	docker-compose.yaml: octo-docs-backend `HOCUSPOCUS_PORT: "1234"`
summary-worker	8082	TCP	summary-api ↔ summary-worker	Worker 内部回调	docker-compose.yaml: `WORKER_INTERNAL_PORT: "8082"`
summary-api	8081	TCP	summary-worker → summary-api	Task event 回调	docker-compose.yaml: `API_INTERNAL_PORT: "8081"`
wukongim → octo-server	6979	TCP（gRPC/webhook）	wukongim → octo-server	消息回调（WuKongIM 主动连接 octo-server）	docker-compose.yaml 注释: "gRPC at octo-server:6979"
search-kafka	9092	TCP（PLAINTEXT）	es-indexer/octo-server → kafka	Kafka 内部 listener	docker-compose.yaml: `KAFKA_LISTENERS: PLAINTEXT://0.0.0.0:9092`
search-kafka	9093	TCP（CONTROLLER）	Kafka 内部	KRaft controller	docker-compose.yaml: `CONTROLLER://0.0.0.0:9093`
mysql	3306	TCP	所有服务 → mysql	MySQL 内部访问	docker-compose.yaml
redis	6379	TCP	所有服务 → redis	Redis 内部访问	docker-compose.yaml

1.5 HTTPS 端口（默认禁用，需手动启用）

服务名	Host 端口	容器端口	协议	默认状态	来源
nginx HTTPS	28443	443	TCP	注释状态，需手动取消注释	docker-compose.yaml: 注释行 `# - "${OCTO_HTTPS_PORT:-28443}:443"`; octo.conf.template HTTPS server block 注释

启用 HTTPS 需：(1) 放置证书到 `docker/certs/`，(2) 取消 docker-compose.yaml 中 443 端口映射注释，(3) 取消证书 volume 挂载注释，(4) 取消 octo.conf.template 中 HTTPS server block 注释。参见 docker/certs/README.md。

§2 Nginx 路由表

2.1 限流区域（nginx.conf）

Zone 名称	速率	内存	用途
`octo_api`	30r/s per IP	10MB	API 请求限流
`octo_auth`	10r/s per IP	10MB	认证/SSO 端点限流

2.2 HTTP (80) 路由详情

Location	Upstream	限流	超时	特殊配置	用途
`= /_nginx_up`	直接返回 200	无	—	access_log off	Nginx 健康检查
`/api/`	`octo_api` (octo-server:8090)	octo_api burst=60 nodelay	proxy_read_timeout 600s	Connection ""	REST API
`^~ /v1/`	`octo_api/v1/` (octo-server:8090)	octo_auth burst=20 nodelay	proxy_read_timeout 600s	Connection ""	OIDC/SSO/认证端点
`/ws`	`octo_ws` (wukongim:5200)	无	proxy_read_timeout 3600s, proxy_send_timeout 3600s	Upgrade/Connection upgrade, WebSocket	IM 长连接
`/minio/`	`octo_minio_api` (minio:9000)	无	proxy_read_timeout 600s	proxy_buffering off, 无 path rewrite	MinIO 诊断/健康检查
`~ ^/space(/.*)?$`	301 重定向	—	—	→ /admin/space$1	Space 路由重定向
`= /admin`	301 重定向	—	—	→ /admin/	Admin 尾部斜杠重定向
`/admin/`	`admin:80`（变量解析）	无	默认	resolver 127.0.0.11 valid=10s	管理后台
`/matter/`	`matter:8080`（变量解析）	octo_api burst=20 nodelay	默认	rewrite 去掉 /matter/ 前缀	Matter/AI 助手
`/summary/`	`summary-api:8080`（变量解析）	octo_api burst=20 nodelay	默认	rewrite 去掉 /summary/ 前缀；变量 DNS 实现 profile 可选	智能摘要
`^~ /market/api/`	`marketplace:8092`（变量解析）	octo_api burst=30 nodelay	proxy_read_timeout 180s	client_max_body_size 25m; rewrite → /api/	市场 API
`= /market/healthz`	`marketplace:8092/healthz`	octo_api burst=30 nodelay	—	—	市场健康检查
`/docs-api/`	`octo-docs-backend:3000`（变量解析）	octo_api burst=20 nodelay	默认	rewrite 去掉 /docs-api/ 前缀；变量 DNS	文档 REST API
`= /docs-api`	301 重定向	—	—	→ /docs-api/	文档尾部斜杠重定向
`/docs-ws/`	`octo-docs-backend:1234`（变量解析）	无	proxy_read_timeout 86400s, proxy_send_timeout 86400s	Upgrade/Connection upgrade; rewrite 去掉前缀	文档协作 WebSocket
`= /_octo_up`	直接返回 HTML	无	—	—	服务状态页（含快速链接）
`~ ^/(file\	chat\	moment\	sticker\	report\	chatbg\	common\	download\	group\	avatar\	octo-docs-attachments\	marketplace)/.+`	`octo_minio_api` (minio:9000)	无	proxy_read_timeout 600s	proxy_buffering off, 无 rewrite（保留 SigV4 路径）; bucket 白名单正则	S3 预签名 URL 文件访问
`/`	`web:80`（变量解析）	无	默认	resolver 127.0.0.11 valid=10s	SPA 前端（catch-all）

2.3 安全响应头（所有响应）

X-Frame-Options: SAMEORIGIN
X-Content-Type-Options: nosniff
Referrer-Policy: strict-origin-when-cross-origin
HTTPS 启用时额外添加 Strict-Transport-Security: max-age=63072000; includeSubDomains

2.4 通用配置

client_max_body_size: 1000m（market/api 路径单独限制为 25m）
server_tokens off（隐藏 Nginx 版本）
Gzip 压缩启用（text/css, application/json, application/javascript 等）
Docker 内嵌 DNS resolver 127.0.0.11 valid=10s ipv6=off（容器重建后自动重新解析）

§3 默认防火墙规则建议

3.1 场景一：单机评估（本机/localhost 访问）

# ufw 示例：只允许本机访问
ufw default deny incoming
ufw default allow outgoing
ufw allow from 127.0.0.1 to any port 28080
ufw enable

3.2 场景二：内网生产（公司内网/VPN 环境）

# ufw 示例
ufw default deny incoming
ufw default allow outgoing

# SSH（限制来源 IP 或网段）
ufw allow from 10.0.0.0/8 to any port 22 proto tcp

# OCTO HTTP 入口（限制内网网段）
ufw allow from 10.0.0.0/8 to any port 28080 proto tcp
ufw allow from 172.16.0.0/12 to any port 28080 proto tcp
ufw allow from 192.168.0.0/16 to any port 28080 proto tcp

# 如启用 HTTPS
# ufw allow from 10.0.0.0/8 to any port 28443 proto tcp

ufw enable

⚠️ 重要：ufw 规则对 Docker 发布端口不完全生效，参见 §4。

3.3 场景三：公网生产（互联网可访问）

# ufw 示例
ufw default deny incoming
ufw default allow outgoing

# SSH（仅信任 IP）
ufw allow from <管理员IP> to any port 22 proto tcp

# OCTO HTTP/HTTPS
ufw allow 80/tcp    # 如需 HTTP→HTTPS 重定向
ufw allow 443/tcp   # HTTPS（如 Nginx 直接 TLS）
# 或者如使用非标准端口：
# ufw allow 28080/tcp
# ufw allow 28443/tcp

ufw enable

将 `OCTO_NGINX_BIND` 改为 `127.0.0.1`（前置 LB/反向代理时）或确认直接暴露的安全
所有密码和 Token 必须从占位符改为强随机值（参见 §7）
启用 HTTPS
考虑 fail2ban 等防暴力破解措施
所有 `*_BIND` 变量保持 `127.0.0.1` 默认值

§4 Docker iptables 绕过问题

4.1 问题说明

即使 ufw deny 28080，如果 Docker 通过 -p 0.0.0.0:28080:80 发布了端口，外部仍然可以访问
这是 Docker 已知行为（[moby/moby#690](https://github.com/moby/moby/issues/690)），不是 bug

4.2 验证方法

# 查看 Docker 发布的端口实际绑定情况
docker ps --format "table {{.Names}}\t{{.Ports}}"

# 查看 iptables DOCKER chain
sudo iptables -L DOCKER -n -v

# 查看实际监听的地址
sudo ss -tlnp | grep -E '28080|23306|26379|29000|29001|25'

4.3 解决方案

# 禁止外部访问 23306（MySQL）- 以实际发布的端口为例
iptables -I DOCKER-USER -p tcp --dport 23306 -j DROP

# 只允许内网访问 28080
iptables -I DOCKER-USER -p tcp --dport 28080 ! -s 10.0.0.0/8 -j DROP

# .env 中
OCTO_NGINX_BIND=127.0.0.1

§5 Profile 可选模块端口说明

5.1 Summary（智能摘要）

Profile: summary
启用命令: COMPOSE_PROFILES=summary docker compose up -d
Host 端口: 28087（summary-api 直连，loopback）
Nginx 路由: /summary/ → summary-api:8080（含限流、prefix strip）
内部端口: summary-worker:8082（回调），summary-api:8081（内部 API）
不需要额外防火墙开放

5.2 Speech（语音转写）

Profile: speech
启用前必须运行 docker/scripts/speech-setup.sh 并配置所有凭证
Host 端口: 28088（speech-admin 直连，loopback，SSH 隧道访问）
内部端口: octo-speech:8780（octo-server 内部调用，无 host 映射）
Nginx 不代理 speech-admin（与 MinIO Console 同理），需 SSH 隧道：

  ssh -L 28088:127.0.0.1:28088 user@host
  # 浏览器访问 http://localhost:28088

不需要额外防火墙开放

5.3 Docs（实时协作文档）

Profile: docs
启用前必须配置所有 secrets（OCTO_DOCS_DB_PASSWORD, OCTO_DOCS_COLLAB_SECRET, OCTO_DOCS_ATTACHMENT_SECRET 等）
Host 端口: 无（所有流量经 Nginx）
Nginx 路由:
/docs-api/ → octo-docs-backend:3000（REST API，含限流）
/docs-ws/ → octo-docs-backend:1234（Hocuspocus WebSocket，86400s 超时）
不需要额外防火墙开放

5.4 Marketplace（技能/插件市场）

默认启用（无 profile 限制），但需要设置 OCTO_MARKETPLACE_DB_PASSWORD
Host 端口: 无（纯内部服务，经 Nginx 代理）
Nginx 路由: /market/api/ → marketplace:8092（含限流，25m 上传限制）
不需要额外防火墙开放

5.5 Search（消息搜索）

Profile: search
Host 端口: 29200（OpenSearch）、29092（Kafka EXTERNAL），均默认绑定 127.0.0.1
内部端口: kafka:9092（PLAINTEXT 内部 listener）、opensearch:9200、es-indexer 无端口
这些 host 端口用于本地验证/调试工具，不应开放防火墙
octo-server 通过 OCTO_SEARCH_BACKEND=es 启用搜索功能（独立开关，profile 启用后需手动设置）

5.6 Fleet / Loop 模块

⚠️ 本文档v1.0暂未覆盖 Fleet/Loop 模块端口。Fleet模块确实存在于内部版 docker-compose.yaml（profiles: ["fleet"]，octo-fleet容器端口8080，fleet-postgres容器端口5432，宿主机映射28089/25432），详见《OCTO全组件服务清单》§十和《基础设施依赖映射》§八。完整端口表和防火墙规则待v1.1补齐。

5.7 Drive 模块

⚠️ 本文档v1.0暂未覆盖 Drive 模块端口。Drive模块确实存在于内部版 docker-compose.yaml（profiles: ["drive"]，octo-drive容器端口8080），详见《OCTO全组件服务清单》§十一和《基础设施依赖映射》§八。完整端口表和防火墙规则待v1.1补齐。

5.8 docs-html / doc-index / drive-index / tika 模块

⚠️ 本文档v1.0暂未覆盖：docs-html(docs-html:8080 profile:docs-html)、doc-indexer(3100 profile:doc-index)、drive-indexer(3200 profile:drive-index)、tika(9998 profile:drive-index) 等模块端口。详见《OCTO全组件服务清单》§七/§十二/§十三。待v1.1补齐。

§6 Kubernetes / Helm 部署端口差异

项目	Docker Compose	K8s/Helm
网络模型	Docker bridge `octo-net`（172.28.0.0/24）	Kubernetes ClusterIP Services + CoreDNS
对外暴露	Nginx 容器端口映射 → host:28080	Nginx Service `ClusterIP` 类型，端口 80；通过 Ingress 或 NodePort 暴露
NodePort	不适用	可选 `nginx.service.nodePort: 30080`（默认注释）
内部通信	容器名:端口（Docker DNS）	Service 名:端口（CoreDNS，`*.default.svc.cluster.local`）
MySQL	mysql:3306（容器）→ 127.0.0.1:23306（host）	mysql Service:3306（ClusterIP），支持 `mysql.enabled: false` 使用外部 MySQL
Redis	redis:6379（容器）→ 127.0.0.1:26379（host），无密码	redis Service:6379（ClusterIP），可选 `secrets.redisPassword` 启用 AUTH
MinIO Console	不通过 Nginx，SSH 隧道 :29001	minio Service:9001（ClusterIP），默认不通过 Ingress 暴露
WuKongIM	4 个端口映射到 host loopback	wukongim Service: 5001/5100/5200/5300（ClusterIP）
Profile 服务	通过 COMPOSE_PROFILES 控制	通过 `summary.enabled`, `speech.enabled`, `docs.enabled`, `marketplace.enabled`, `search.enabled` 布尔值控制
TLS	手动配置 Nginx 443 + certs 目录	通过 Ingress TLS（`ingress.tls.enabled`）或 cert-manager
外部存储	默认 MinIO	支持 tencentCOS / aliOSS / s3 / qiniu（通过 `server.config.fileService` 切换）
WuKongIM 版本	wukongim/wukongim:v2.2.4-20260313	wukongim/wukongim:v2.2.5-20260422（更新）
octo-server 版本	mininglamposs/octo-server:latest	mininglamposs/octo-server:1.6.0（固定版本）

所有内部服务使用 ClusterIP，默认不从集群外部可达
通过 Ingress Controller（如 nginx-ingress、TKE CLB）暴露服务时，只暴露 80/443
NodePort 方式暴露时，默认端口范围 30000-32767，可通过 nginx.service.nodePort 指定
网络策略（NetworkPolicy）可用于进一步限制 Pod 间通信（Helm chart 当前未内置，需自行添加）
当 minio.enabled=false 使用云对象存储时，安全组需放通到对应 COS/OSS/S3 端点的出站流量

§7 安全检查清单

7.1 绝不能暴露公网的端口

端口	服务	风险
23306	MySQL	数据库暴露，root 密码被猜解可导致全库泄露/篡改
26379	Redis	默认无密码，暴露后可读写所有缓存/会话数据（包括 token）
29001	MinIO Console	MinIO 管理控制台，root 密码泄露则全量对象存储失控
25001	WuKongIM Manager API	WuKongIM 管理接口，token 泄露可操作 IM 所有数据
25100	WuKongIM TCP	原生 TCP 长连接端口，绕过 Nginx 限流
25200	WuKongIM WS	WebSocket 直连端口，绕过 Nginx 限流
25300	WuKongIM Monitor	监控/varz 接口，泄露内部拓扑信息
28081	octo-server 直连	绕过 Nginx 限流，可直接调用所有 API
28082	admin 直连	绕过 Nginx 直接访问管理后台
28083	web 直连	绕过 Nginx 直接访问前端
28086	matter 直连	绕过 Nginx 限流直接访问 matter 服务
28088	speech-admin	语音管理控制台（含 API Key 管理）
29000	MinIO API 直连	绕过 Nginx 直接访问 S3 API
29092	Kafka	消息队列暴露，可注入/消费消息
29200	OpenSearch	搜索索引暴露，可读取/删除所有索引数据

7.2 必须修改的默认密码/Token

变量名	默认占位符	生成方式	校验机制
`MYSQL_ROOT_PASSWORD`	`CHANGE_ME_MYSQL_PASSWORD`	`openssl rand -hex 16`	init-extra-dbs.sh 拦截 CHANGE_ME/CHG_ME/空值
`MINIO_ROOT_PASSWORD`	`CHG_ME!`（7 字符，故意触发 MinIO ≥8 校验）	`openssl rand -hex 16`	MinIO 自身 ≥8 校验 + minio-init 拦截
`OCTO_MINIO_APP_PASSWORD`	`CHANGE_ME_MINIO_APP_PASSWORD`	`openssl rand -hex 24`	minio-init 拦截
`OCTO_MASTER_KEY`	`CHANGE_ME_32_BYTES_octo_master_`（31 字符，故意触发 32 字节校验）	`openssl rand -hex 16`（32 字节）	octo-server 启动校验
`OCTO_NOTIFY_INTERNAL_TOKEN`	`CHANGE_ME_notify_internal_token`	`openssl rand -hex 32`	preflight 拦截
`OCTO_WUKONGIM_MANAGER_TOKEN`	`CHANGE_ME_wukongim_manager_token`	`openssl rand -hex 32`	preflight 拦截
`OCTO_MATTER_DB_PASSWORD`	`matter`（字面默认值）	`openssl rand -hex 16`	init-extra-dbs.sh + market-preflight 同模式拦截
`OCTO_SUMMARY_DB_PASSWORD`	`summary`（字面默认值）	`openssl rand -hex 16`	init-extra-dbs.sh 拦截
`OCTO_SUMMARY_READER_PASSWORD`	`summary_reader`（字面默认值）	`openssl rand -hex 16`	init-extra-dbs.sh 拦截
`OCTO_MARKETPLACE_DB_PASSWORD`	`CHANGE_ME_marketplace_db_pass`	`openssl rand -hex 16`	market-preflight 拦截
`OCTO_ADMIN_PWD`	空（不自动 bootstrap）	`openssl rand -hex 16`	非强制，空值跳过
`LLM_API_KEY`	空	从 LLM 服务商获取	summary-worker 启动时校验

7.3 部署前安全确认清单

[ ] 所有 CHANGE_ME_* / CHG_ME* 占位符已替换为强随机值
[ ] MySQL 密码仅使用 [A-Za-z0-9._-] 字符
[ ] OCTO_MASTER_KEY 恰好 32 字节（hex 32 字符）
[ ] 所有 *_BIND 变量保持 127.0.0.1（除 OCTO_NGINX_BIND 外）
[ ] Redis 未暴露公网（默认无密码，暴露即失守）
[ ] MinIO Console 未通过 Nginx 暴露（默认配置已满足）
[ ] 如启用 speech profile，已设置 SPEECH_ADMIN_PASSWORD 和 SPEECH_ADMIN_JWT_SECRET
[ ] 如启用 docs profile，已设置所有 OCTO_DOCS_* 密钥
[ ] 如启用 search profile 且用于生产，已启用 OpenSearch security plugin（OCTO_SEARCH_OPENSEARCH_DISABLE_SECURITY=false）
[ ] Docker iptables 绕过问题已处理（参见 §4）
[ ] SSH 不使用默认密码，推荐密钥认证
[ ] 已配置防火墙规则（参见 §3）

§8 常见网络排障命令

8.1 端口监听检查

# 查看所有端口监听情况
sudo ss -tlnp

# 查看特定端口
sudo ss -tlnp | grep -E '28080|23306|26379'

# Docker 端口映射
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

# 查看容器内部监听
docker exec octo-nginx-1 ss -tlnp
docker exec octo-octo-server-1 ss -tlnp

8.2 健康检查

# Nginx 健康检查
curl -fsS http://localhost:28080/_nginx_up && echo "OK"

# 服务状态页（含所有服务链接）
curl -fsS http://localhost:28080/_octo_up

# octo-server API 健康
curl -fsS http://localhost:28080/api/v1/ping
curl -fsS http://localhost:28080/api/v1/health

# 直连 octo-server（绕过 Nginx，验证服务本身）
curl -fsS http://localhost:28081/v1/ping

# MinIO 健康（通过 Nginx）
curl -fsS http://localhost:28080/minio/health/live

# Matter 健康（通过 Nginx）
curl -fsS http://localhost:28080/matter/health

# Summary 健康（通过 Nginx，需 summary profile）
curl -fsS http://localhost:28080/summary/health

# Marketplace 健康
curl -fsS http://localhost:28080/market/healthz

# Docs 健康（需 docs profile）
curl -fsS http://localhost:28080/docs-api/healthz

8.3 WebSocket 测试

# 使用 wscat 测试 WebSocket（需 npm install -g wscat）
wscat -c ws://localhost:28080/ws

# 文档协作 WebSocket（需 docs profile）
wscat -c ws://localhost:28080/docs-ws/

8.4 日志查看

# Nginx 访问/错误日志
docker logs octo-nginx-1 --tail 100 -f
docker exec octo-nginx-1 tail -100 /var/log/nginx/error.log

# octo-server 日志
docker logs octo-octo-server-1 --tail 100 -f

# WuKongIM 日志
docker logs octo-wukongim-1 --tail 100 -f

# MySQL 日志
docker logs octo-mysql-1 --tail 50

# 所有服务健康状态
docker ps --format "table {{.Names}}\t{{.Status}}"

8.5 Docker 网络排查

# 查看 octo-net 网络详情
docker network inspect octo_octo-net

# 从容器内部测试连通性
docker exec octo-nginx-1 wget -q -O - http://octo-server:8090/v1/ping
docker exec octo-nginx-1 wget -q -O - http://wukongim:5200
docker exec octo-octo-server-1 wget -q -O - http://redis:6379
docker exec octo-octo-server-1 wget -q -O - http://minio:9000/minio/health/live

# 测试容器 DNS 解析
docker exec octo-nginx-1 nslookup octo-server
docker exec octo-nginx-1 nslookup wukongim

8.6 iptables / 防火墙排查

# 查看 DOCKER chain 规则
sudo iptables -L DOCKER -n -v --line-numbers

# 查看 DOCKER-USER chain
sudo iptables -L DOCKER-USER -n -v

# 查看 ufw 状态
sudo ufw status verbose

# 检查特定端口是否可达（从另一台机器）
nc -zv  28080
nmap -p 28080,23306,26379,29000,29001

8.7 SSH 隧道访问内部服务

# MinIO Console（:9001 容器 / :29001 host）
ssh -L 9001:127.0.0.1:29001 user@host
# 浏览器: http://localhost:9001

# WuKongIM Manager API（:5001 容器 / :25001 host）
ssh -L 5001:127.0.0.1:25001 user@host
# 浏览器: http://localhost:5001/

# Speech Admin（:8781 容器 / :28088 host）
ssh -L 28088:127.0.0.1:28088 user@host
# 浏览器: http://localhost:28088

附录：端口快速参考卡

对外必须开放:
  TCP 28080  → Nginx HTTP 统一入口（默认）
  TCP 28443  → Nginx HTTPS（手动启用后）

绝不开放公网（保持 127.0.0.1）:
  23306 MySQL | 26379 Redis(无密码!) | 29000 MinIO API | 29001 MinIO Console
  25001 WK API | 25100 WK TCP | 25200 WK WS | 25300 WK Monitor
  28081 server | 28082 admin | 28083 web | 28086 matter
  28087 summary-api | 28088 speech-admin
  29092 Kafka | 29200 OpenSearch

容器间（Docker 内部，不经过 host）:
  mysql:3306 | redis:6379 | minio:9000 | wukongim:5200(WS)
  octo-server:8090 | marketplace:8092 | matter:8080
  octo-speech:8780 | octo-docs-backend:3000/1234
  search-kafka:9092 | search-opensearch:9200