# Technical Documentation: Openwrt-Passwall/openwrt-passwall

> ℹ️ **Provenance:** In-Tree Documentation (10 Chapters) · [CodeWiki Reference](https://codewiki.google/github.com/Openwrt-Passwall/openwrt-passwall) · Recency: Active (< 180 days)

## File: README.md

## 📌如何能编译到最新代码？

### 方法1：

执行 `./scripts/feeds update -a` 操作前，在 `feeds.conf.default` **顶部**插入如下代码：

```
src-git passwall_packages https://github.com/Openwrt-Passwall/openwrt-passwall-packages.git;main
src-git passwall_luci https://github.com/Openwrt-Passwall/openwrt-passwall.git;main
```

### 方法2：

在 `./scripts/feeds install -a` 操作完成后，执行以下命令：

```shell
# 移除 openwrt feeds 自带的核心库
rm -rf feeds/packages/net/{xray-core,v2ray-geodata,sing-box,chinadns-ng,dns2socks,hysteria,ipt2socks,microsocks,naiveproxy,shadowsocks-rust,shadowsocksr-libev,simple-obfs,tcping,v2ray-plugin,xray-plugin,geoview,shadow-tls,smartdns}
git clone https://github.com/Openwrt-Passwall/openwrt-passwall-packages package/passwall-packages

# 移除 openwrt feeds 过时的luci版本
rm -rf feeds/luci/applications/luci-app-passwall
git clone https://github.com/Openwrt-Passwall/openwrt-passwall package/passwall-luci
```

## 🚀 配套固件与工具

### 🔥 [OpenWrtAction](https://github.com/smallprogram/OpenWrtAction) —— 开箱即用的 Passwall 固件

[](https://github.com/smallprogram/OpenWrtAction)

基于 GitHub Actions 全自动云编译的固件仓库，集成最新 Passwall，刷入即用，无需自行折腾编译环境。

- 📦 **多源码分支**：官方 OpenWrt 25.12、ImmortalWrt 25.12、Lean (Snapshot)
- 🖥️ **多设备覆盖**：x86、R2S、R2C、R4S、R5S、R5C、H66K、H68K、H69K、R66S、R68S 等
- 🔄 **持续更新**：CI 自动构建，紧跟上游与 Passwall 最新版本
- ⚡ **GitHub 一键更新**：支持直接从 GitHub Releases 一键在线升级固件，告别手动下载、上传、刷写

👉 前往下载：[OpenWrtAction Releases](https://github.com/smallprogram/OpenWrtAction/releases)

### 🧩 [Are-u-ok](https://github.com/bcseputetto/Are-u-ok) —— iStoreOS `.run` 更新包

[](https://github.com/bcseputetto/Are-u-ok)

为 **iStoreOS** 用户提供 `.run` 格式的 Passwall 更新包，无需重刷固件，上传到设备执行即可完成安装/升级。

👉 前往获取：[Are-u-ok](https://github.com/bcseputetto/Are-u-ok)

---

---

## File: luci-app-passwall/root/usr/share/rpcd/acl.d/luci-app-passwall.json

{
	"luci-app-passwall": {
		"description": "Grant UCI access for luci-app-passwall",
		"read": {
			"uci": [ "passwall", "passwall_server" ]
		},
		"write": {
			"uci": [ "passwall", "passwall_server" ]
		}
	}
}

---

## File: luci-app-passwall/root/usr/share/ucitrack/luci-app-passwall-server.json

{
	"config": "passwall_server",
	"init": "passwall_server"
}

---

## File: luci-app-passwall/root/usr/share/ucitrack/luci-app-passwall.json

{
	"config": "passwall",
	"init": "passwall"
}

---

## File: .github/ISSUE_TEMPLATE/bug.yml

[Binary file]

---

## File: .github/ISSUE_TEMPLATE/config.yml

blank_issues_enabled: false

---

## File: .github/ISSUE_TEMPLATE/feature.yml

name: 功能请求
title: "[Feature Request]: "
labels: enhancement

body:
  - type: textarea
    id: description
    attributes:
      label: 描述你想要的新功能
    validations:
      required: true

  - type: textarea
    id: ideal-solution
    attributes:
      label: 描述你想要的解决方案
    validations:
      required: true

  - type: textarea
    id: other-solutions
    attributes:
      label: 描述你考虑过的替代方案
    validations:
      required: false

  - type: textarea
    id: supplements
    attributes:
      label: 其他信息
    validations:
      required: false

---

## File: .github/workflows/Auto compile with openwrt sdk.yml

#
# Copyright (c) 2022-2025 SMALLPROGRAM <https://github.com/smallprogram>
# Copyright (C) 2026 Openwrt-Passwall Organization
#
name: "Auto compile with openwrt sdk"
on:
  repository_dispatch:
  workflow_dispatch:
    inputs:
      ssh:
        required: false
        default: 'false'
env:
  TZ: Asia/Shanghai
  passwall: ${{ github.repository }}
  packages: Openwrt-Passwall/openwrt-passwall-packages

permissions:
  contents: write
  actions: write

jobs:
  job_check:
    name: Check Version
    runs-on: ubuntu-26.04
    outputs:
      passwall_version: ${{ steps.check_version.outputs.latest_version }}
      has_update: ${{ steps.check_version.outputs.has_update }}
      prerelease: ${{ steps.check_version.outputs.prerelease }}
    steps:
      - name: Checkout
        uses: actions/checkout@main
        with:
          fetch-depth: 0
          ref: ${{ github.ref_name }}

      - name: Check version
        id: check_version
        env:
          url_tags: https://api.github.com/repos/${{ env.passwall }}/releases/latest
        run: |
          cd luci-app-passwall
          latest_version=$(awk -F ':=' '/^PKG_VERSION:=|^PKG_RELEASE:=/ {print $2}' Makefile | sed ':a;N;s/\$(PKG_VERSION)-//;s/\n$//;s/\n/-/;ba')
          echo "latest_version=${latest_version}" >> $GITHUB_OUTPUT

          prerelease=$([ "${{ github.ref_name }}" == "main" ] && echo false || echo true)
          echo "prerelease=${prerelease}" >> $GITHUB_OUTPUT

          remote_latest_version=$(wget -qO- -t1 -T2 ${{env.url_tags}} | jq -r '.tag_name')

          if [ -z "$remote_latest_version" ] || [ "$remote_latest_version" = "null" ]; then
            echo "Failed to fetch remote tags"
            echo "has_update=true" >> $GITHUB_OUTPUT
            exit 0
          fi
          echo "Remote latest: $remote_latest_version"

          if [ "$latest_version" = "$remote_latest_version" ]; then
            echo "has_update=false" >> $GITHUB_OUTPUT
          else
            echo "has_update=true" >> $GITHUB_OUTPUT
          fi

      - name: Prepare release
        if: steps.check_version.outputs.has_update == 'true'
        run: |
          echo "" >> release.txt
          echo "## :mega: 获取其他软件包 / How to Get Other Packages" >>release.txt
          echo "" >>release.txt
          echo "### 方式 1：添加软件源 / Method 1: Add Software Source" >>release.txt
          echo " * 请按照 [openwrt-passwall-build](https://github.com/moetayuko/openwrt-passwall-build) 仓库的说明，将其提供的软件源添加到设备中，然后直接使用包管理器安装。" >>release.txt
          echo "  Follow the instructions in the [openwrt-passwall-build](https://github.com/moetayuko/openwrt-passwall-build) repository to add the provided software source to your device, then install directly using the package manager." >>release.txt
          echo "" >>release.txt
          echo "### 方式 2：手动下载并安装 / Method 2: Manual Download and Install" >>release.txt
          echo "" >>release.txt
          echo "* 从 [SourceForge](https://sourceforge.net/projects/openwrt-passwall-build/files/) 下载预构建的软件包。" >>release.txt
          echo "  Download prebuilt packages from [SourceForge](https://sourceforge.net/projects/openwrt-passwall-build/files/)." >>release.txt
          echo "" >>release.txt
          echo "* 将文件上传到您的设备，使用 Shell 命令进行安装。" >>release.txt
          echo "  Upload files to your device, install it with shell command." >>release.txt
          echo "" >>release.txt
          echo "ipk" >>release.txt
          echo "\`\`\`" >>release.txt
          echo "opkg install /path/to/package.ipk" >>release.txt
          echo "\`\`\`" >>release.txt
          echo "apk" >>release.txt
          echo "\`\`\`" >>release.txt
          echo "apk add --allow-untrusted /path/to/package.apk" >>release.txt
          echo "\`\`\`" >>release.txt
          echo "" >>release.txt
          echo ":warning: 请将 /path/to/package 替换为实际下载的软件包路径。" >>release.txt
          echo "- Replace /path/to/package with the actual path of the downloaded packages." >>release.txt
          echo "" >>release.txt
          echo "---" >>release.txt
          echo "## :rocket: 配套固件与工具 / Firmwares & Tools" >>release.txt
          echo "" >>release.txt
          echo "### :fire: [OpenWrtAction](https://github.com/smallprogram/OpenWrtAction) —— 集成 Passwall 的 CI 固件 / Ready-to-use firmware with Passwall" >>release.txt
          echo "* 集成官方 OpenWrt 25.12、ImmortalWrt 25.12、Lean (Snapshot) 固件，支持 x86、R2S、R2C、R4S、R5S、R5C、H66K、H68K、H69K、R66S、R68S 等设备，刷入即用。" >>release.txt
          echo "  Firmware built on official OpenWrt 25.12, ImmortalWrt 25.12 and Lean (Snapshot), supporting x86, R2S, R2C, R4S, R5S, R5C, H66K, H68K, H69K, R66S, R68S and more." >>release.txt
          echo "* 支持 GitHub 一键更新：直接从 GitHub Releases 在线升级固件，无需手动下载和刷写。" >>release.txt
          echo "  Supports one-click GitHub update: upgrade the firmware online straight from GitHub Releases, no manual download or flashing needed." >>release.txt
          echo "" >>release.txt
          echo "### :package: [Are-u-ok](https://github.com/bcseputetto/Are-u-ok) —— iStoreOS .run 更新包 / iStoreOS .run update packages" >>release.txt
          echo "* 为 iStoreOS 提供 .run 格式更新包，无需重刷固件，上传执行即可安装/升级。" >>release.txt
          echo "  Provides .run update packages for iStoreOS — no reflashing needed, just upload and run." >>release.txt
          touch release.txt

      - name: Generate new tag & release
        if: steps.check_version.outputs.has_update == 'true'
        uses: softprops/action-gh-release@v3
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag_name: ${{steps.check_version.outputs.latest_version}}
          target_commitish: ${{ github.ref_name }}
          prerelease: ${{steps.check_version.outputs.prerelease}}
          body_path: release.txt


  job_build_passwall:
    name: Build passwall [${{ matrix.ver }}]
    needs: job_check
    if: needs.job_check.outputs.has_update == 'true'
    runs-on: ubuntu-26.04
    strategy:
      fail-fast: false
      matrix:
        include:
          - container_tag: x86_64-21.02.7
            ver: "22.03-"

          - container_tag: x86_64-24.10.5
            ver: "23.05-24.10"

          - container_tag: x86-64-SNAPSHOT
            ver: "25.12+"
    steps:
      - name: Checkout
        uses: actions/checkout@main

      - name: Generate .config for Language Packs
        run: |
          echo "CONFIG_ALL_NONSHARED=n" > .config
          echo "CONFIG_ALL_KMODS=n" >> .config
          echo "CONFIG_ALL=n" >> .config
          echo "CONFIG_AUTOREMOVE=n" >> .config
          echo "CONFIG_LUCI_LANG_zh_Hans=y" >> .config
          echo "CONFIG_PACKAGE_luci-app-passwall=m" >> .config

      - name: Compile With OpenWrt SDK
        uses: openwrt/gh-action-sdk@main
        env:
          ARCH: ${{ matrix.container_tag }}
          PACKAGES: luci-app-passwall
          # V: s

      - name: Process and Rename Artifacts
        id: compile
        run: |
          mkdir -p ${{ github.workspace }}/upload
          
          # 使用 find 安全提取生成的 ipk/apk 及语言包
          find bin/packages/ -type f -name "luci-app-passwall*" -exec cp {} ${{ github.workspace }}/upload/ \;
          find bin/packages/ -type f -name "luci-i18n-passwall*" -exec cp {} ${{ github.workspace }}/upload/ \;
          
          cd ${{ github.workspace }}/upload
          
          for i in $(ls); do mv $i ${{ matrix.ver }}_$i; done
          
          echo "status=success" >> $GITHUB_OUTPUT
      - name: Upload to release
        uses: softprops/action-gh-release@v3
        if: steps.compile.outputs.status == 'success'
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag_name: ${{needs.job_check.outputs.passwall_version}}
          files: ${{ github.workspace }}/upload/*

  job_trigger_packages:
    name: Trigger packages cache workflow
    needs: [job_check, job_build_passwall]
    if: needs.job_check.outputs.has_update == 'true' && needs.job_build_passwall.result == 'success'
    runs-on: ubuntu-26.04
    steps:
      - name: Trigger Auto Cache Software Release JSONs
        env:
          # PAT with "Actions: write" permission on the packages repository
          GH_TOKEN: ${{ secrets.PACKAGES_DISPATCH_TOKEN }}
        run: |
          gh workflow run "Auto cache software release jsons.yml" \
            --repo "${{ env.packages }}" \
            --ref main

---

## File: .github/workflows/Close spam issues and PRs.yml

name: "Close spam issues and PRs"

on:
  issues:
    types: [labeled]
  pull_request:
    types: [labeled]

jobs:
  close-item:
    # 检查标签是否为指定的三个之一
    if: >
      github.event.label.name == 'invalid' || 
      github.event.label.name == 'no plan' || 
      github.event.label.name == 'wontfix'
    runs-on: ubuntu-26.04
    permissions:
      issues: write
      pull-requests: write
    steps:
      - name: Close Issue or PR
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NUMBER: ${{ github.event.issue.number || github.event.pull_request.number }}
          EVENT_TYPE: ${{ github.event_name }}
        run: |
          COMMENT="This content has been marked as invalid, no plan or wontfix; the system has automatically closed it."
          LABEL_TO_ADD="closed-by-bot"
          # 使用 Actions 自带的环境变量指定仓库
          REPO="$GITHUB_REPOSITORY" 
          
          if [ "$EVENT_TYPE" == "issues" ]; then
            gh issue edit $NUMBER --repo "$REPO" --add-label "$LABEL_TO_ADD"
            gh issue close $NUMBER --repo "$REPO" --comment "$COMMENT" --reason "not planned"
          else
            gh pr edit $NUMBER --repo "$REPO" --add-label "$LABEL_TO_ADD"
            gh pr close $NUMBER --repo "$REPO" --comment "$COMMENT"
          fi

---

## File: .github/workflows/Close stale issues and PRs.yml

name: "Close stale issues and PRs"
on:
  schedule:
    - cron: "30 1 * * *"

jobs:
  stale:
    runs-on: ubuntu-26.04
    permissions:
      issues: write
      actions: write
    steps:
      - name: Close stale issue and pr
        uses: actions/stale@v10
        with:
          stale-issue-message: "Stale Issue"
          stale-pr-message: "Stale PR"
          stale-issue-label: "no-issue-activity"
          exempt-issue-labels: "awaiting-approval,awaiting,work-in-progress"
          stale-pr-label: "no-pr-activity"
          exempt-pr-labels: "awaiting-approval,awaiting,work-in-progress,automated-pr"
          # only-labels: 'bug,enhancement'
          days-before-issue-stale: 10
          days-before-pr-stale: 10
          days-before-issue-close: 5
          days-before-pr-close: -1
          operations-per-run: 500

      # - name: Delete workflow runs
      #   uses: Mattraks/delete-workflow-runs@main
      #   with:
      #     token: ${{ github.token }}
      #     repository: ${{ github.repository }}
      #     retain_days: 1
      #     keep_minimum_runs: 0

--- METRICS ---
- Files Extracted: 10
- Estimated Token Budget: ~4164 tokens
- Recency Window: Active (< 180 days)
- Canonical Reference: https://codewiki.google/github.com/Openwrt-Passwall/openwrt-passwall